API & MCP

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

REST API

All endpoints live under https://api.yo.urspace.net/v1. Pass your bearer token via the standard Authorization: Bearer header; the CLI reads it from $YOURSPACE_TOKEN.

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": "2026-04-22T09: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/sites/:name/domains

Bind a custom domain to a site. Returns a one-time verification token and the txt_record to publish at your DNS provider. The binding is reserved but inactive (verified: false) until you prove ownership via the verify endpoint below. See DNS & Certificates for the full point-the-domain → publish-TXT → verify flow.

curl -X POST https://api.yo.urspace.net/v1/sites/my-blog/domains \
  -H "Authorization: Bearer $YOURSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "your-site.com"}'

# Response (201) — publish the txt_record, then call verify
{
  "domain": "your-site.com",
  "token": "ys-verify-9F3aK7pQrX2bV8mN1",
  "txt_record": "_yourspace-verify.your-site.com",
  "verified": false
}

POST /v1/sites/:name/domains/:domain/verify

Check the published TXT record and activate the binding. On success the edge begins routing the domain to the site and an ACME certificate is issued automatically. If the record is missing or the token doesn't match, the API returns 412 with diagnostic detail so you can correct the record and retry.

curl -X POST https://api.yo.urspace.net/v1/sites/my-blog/domains/your-site.com/verify \
  -H "Authorization: Bearer $YOURSPACE_TOKEN"

# Response (200) — binding activates; ACME certificate is issued
{
  "domain": "your-site.com",
  "verified": true,
  "verified_at": "2026-04-19T20:14:07Z"
}

DELETE /v1/sites/:name/domains/:domain

Unbind a custom domain. The edge stops serving the hostname for this site.

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

# Response (200)
{ "status": "removed" }

GET /v1/sites/:name/metrics

Read a site's traffic as a time series — a per-minute count of requests, scoped to one site and gated by your token. See Analytics & Privacy for what is measured and how the aggregate-by-design model works.

GET /v1/sites/:name/logs

Tail recent access-log entries for a site. Filtering is server-side: only requests to the site's canonical :name.yo.urspace.net host (and any verified custom domains, returned in hosts) appear. Each element of lines is a raw edge access-log JSON record, passed through untouched; count is how many were returned. Backs the yourspace logs command.

Query parameters:

• tail — number of most-recent matching entries to return. Defaults to 100; values above 1000 (or non-positive) return 400.
• since — lower-bound the entries by age. Accepts either a duration (15m, 1h, 30s, 1d, 1w) measured back from now, or an absolute RFC 3339 timestamp (2026-04-27T10:00:00Z). Omit to return the most recent entries regardless of age.

curl "https://api.yo.urspace.net/v1/sites/my-blog/logs?tail=100&since=15m" \
  -H "Authorization: Bearer $YOURSPACE_TOKEN"

# Response — each entry in "lines" is a raw edge access-log record
{
  "site": "my-blog",
  "hosts": ["my-blog.yo.urspace.net", "your-site.com"],
  "count": 2,
  "lines": [
    { "ts": 1745314320.12, "request": { "host": "my-blog.yo.urspace.net", "method": "GET", "uri": "/" }, "status": 200 }
  ]
}

GET /v1/sites/:name/deploys

List a site's retained deploy versions, newest first, alongside current_version. Each entry carries its version, deployed_at, bundle_hash, and a current flag marking the live one. The CLI uses this to find the previous version's number before a rollback; pair it with POST /v1/sites/:name/version to flip the live pointer.

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

# Response — retained versions, newest first; "current" marks the live one
{
  "name": "my-blog",
  "current_version": 4,
  "deploys": [
    { "version": 4, "deployed_at": "2026-04-22T09:12:00Z", "bundle_hash": "sha256:abc…", "current": true },
    { "version": 3, "deployed_at": "2026-04-21T18:40:00Z", "bundle_hash": "sha256:def…", "current": false }
  ]
}

POST /v1/sites/:name/version

Flip the live version pointer to a retained version — the rollback / roll-forward operation, with no re-upload. The body is {"version": N} where N is a positive integer naming one of the versions returned by GET /v1/sites/:name/deploys; a version not in the retained set returns 404. The call is idempotent: re-posting the version that's already live is a no-op and returns unchanged: true. The response reports the new version, the prior_version that was live before, and the now-live deploy's bundle_hash and deployed_at. Backs yourspace rollback.

curl -X POST https://api.yo.urspace.net/v1/sites/my-blog/version \
  -H "Authorization: Bearer $YOURSPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 3}'

# Response — "prior_version" is what was live before; "unchanged" is true on a no-op
{
  "status": "ok",
  "name": "my-blog",
  "version": 3,
  "prior_version": 4,
  "unchanged": false,
  "bundle_hash": "sha256:def…",
  "deployed_at": "2026-04-21T18:40:00Z"
}

POST /v1/tokens

Mint a scoped API token. Useful for CI or agent contexts where the CLI isn't available. owner names the principal; tier is tester for customer-minted credentials; scopes and capabilities define the grant. The response returns the plaintext bearer once — copy it into your secret store immediately, the server cannot show it again. The CLI wraps this endpoint as yourspace token create.

curl -X POST https://api.yo.urspace.net/v1/tokens \
  -H "Authorization: Bearer $YOURSPACE_TOKEN" \
  -d '{
    "owner": "me",
    "tier": "tester",
    "scopes": ["deploy", "read"],
    "capabilities": [{ "action": "deploy", "resource_pattern": "site:my-blog" }],
    "label": "github-actions"
  }'

# Response — the plaintext is shown once; store it now.
{ "id": "tok_...", "plaintext": "ys_live_..." }

MCP Server

YourSpace will expose 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

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

{}

{ "name": "my-blog" }

{ "name": "my-blog" }

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

Tips for Agent Authors

• Use scoped tokens (deploy only) so a compromised agent can't delete sites — mint them with POST /v1/tokens above.
• After a deploy, read back GET /v1/sites/:name to confirm the site is live before reporting success.
• Point agents at a short-lived token (set an expires_at) so a leaked credential ages out on its own.

When the MCP server (above) ships, these same patterns apply through the typed tool surface — a bundle_url input for out-of-band artifacts and Streamable HTTP transport are part of that planned design.