API & MCP

Everything an agent (or a crafty shell script) needs to deploy sites programmatically — no CLI required.

REST API

All endpoints live under https://api.yo.urspace.net/v1. Authenticate with a bearer token generated via yourspace token or the key creation flow described in Deploy.

POST /v1/sites

Create or update a site. Accepts a .tar.gz bundle and an optional config override.

curl -X POST https://api.yo.urspace.net/v1/sites \
  -H "Authorization: Bearer $YOURSPACE_TOKEN" \
  -F "bundle=@dist.tar.gz" \
  -F "config=@yourspace.yml"

GET /v1/sites

List sites associated with the current token.

curl https://api.yo.urspace.net/v1/sites \
  -H "Authorization: Bearer $YOURSPACE_TOKEN"

# Response
{
  "sites": [
    { "name": "my-blog", "nodes": 22, "last_deploy": "2025-02-14T09:12:00Z" }
  ]
}

GET /v1/sites/:name

Fetch deployment status and active routing config for a site.

curl https://api.yo.urspace.net/v1/sites/my-blog \
  -H "Authorization: Bearer $YOURSPACE_TOKEN"

# Response
{
  "name": "my-blog",
  "status": "live",
  "nodes": ["iad", "cdg", "gru", "sin"],
  "config": { "routes": [ ... ] }
}

DELETE /v1/sites/:name

Tear down a site and purge it from all edge nodes.

curl -X DELETE https://api.yo.urspace.net/v1/sites/my-blog \
  -H "Authorization: Bearer $YOURSPACE_TOKEN"

POST /v1/tokens

Generate a scoped API token. Useful for CI or agent contexts where the CLI isn't available.

curl -X POST https://api.yo.urspace.net/v1/tokens \
  -H "Authorization: Bearer $YOURSPACE_ROOT_KEY" \
  -d '{ "label": "github-actions", "scopes": ["deploy", "read"] }'

# Response
{ "token": "ys_tok_..." }

MCP Server

YourSpace exposes an MCP-compatible tool server so AI agents can deploy, inspect, and tear down sites without shelling out to the CLI.

Connecting

Point your MCP client at the YourSpace server URL. The token is passed via the standard Authorization header.

{
  "mcpServers": {
    "yourspace": {
      "url": "https://mcp.yo.urspace.net",
      "headers": {
        "Authorization": "Bearer $YOURSPACE_TOKEN"
      }
    }
  }
}

Available tools

yourspace_deploy

Deploy a site from a bundle URL or base64 payload. Accepts an optional yourspace.yml config override. Returns deployment status and propagated node list.

{ "name": "my-blog", "bundle_url": "https://…/dist.tar.gz" }

yourspace_list_sites

List all sites associated with the current token. Returns name, node count, and last deploy timestamp.

{}

yourspace_get_site

Fetch deployment status, active config, and node allocation for a single site.

{ "name": "my-blog" }

yourspace_delete_site

Tear down a site and purge its bundles from every edge node.

{ "name": "my-blog" }

yourspace_create_token

Mint a scoped API token. Requires a root key. Useful for delegating deploy-only access to CI agents.

{ "label": "ci-bot", "scopes": ["deploy"] }

Tips for Agent Authors

Use scoped tokens (deploy only) so a compromised agent can't delete sites.
The yourspace_deploy tool accepts a bundle_url — point it at a CI artifact or a presigned S3 URL instead of uploading bytes inline.
Poll yourspace_get_site after deploy to confirm propagation across all target nodes before reporting success.
The MCP server supports Streamable HTTP transport — keep-alive connections work if your client supports them.