API Reference

List all apps owned by the authenticated user.

Auth: Bearer token

curl https://api.xhostd.com/apps \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "apps": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "my-site",
      "repo_url": "https://git.xhostd.com/alice/my-site.git",
      "template": "static",
      "created_at": "2026-04-22T10:30:00Z",
      "external_db_access_enabled": false,
      "external_blob_access_enabled": false,
      "port_forwarding_enabled": false,
      "port_forwarding_available": true,
      "agent_protected_actions_enabled": null,
      "agent_protected_actions_effective": false,
      "channels": [
        {
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "name": "prod",
          "hostname": "my-site-alice.xhostd.app",
          "git_ref_binding": "branch:master",
          "current_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
          "status": "running",
          "pending_deploy": null
        }
      ],
      "owner_username": "alice",
      "role": "owner"
    }
  ]
}

role is the caller's role on the app (owner, admin, or member) and owner_username the app owner's username — they differ from the caller only on shared apps. pending_deploy is the channel's newest queued or running deploy ({deploy_id, sha, status}), or null when nothing is in flight; an old current_sha next to a non-null pending_deploy means the deploy has not finished yet, not that it failed. external_db_access_enabled / external_blob_access_enabled report the app's external Postgres and object-store access opt-ins; the toggles themselves are protected actions and answer protected_action (403) to an agent credential, until the app owner turns agent access on in the console. port_forwarding_enabled is the app toggle for public raw-TCP endpoints, and port_forwarding_available reports whether the plan of the app owner includes them. agent_protected_actions_enabled is the raw app override of the agent-access switch. Null means the app inherits the account default of the owner. The console shows three states: Inherit, On and Off. agent_protected_actions_effective is the value that applies now: the override when the owner set it, and otherwise the account default.

Create a new app. Provisions a git repo and a prod channel.

Auth: Bearer token — requires repo:* scope

Request body

curl -X POST https://api.xhostd.com/apps \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-site", "template": "static"}'

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "my-site",
  "repo_url": "https://git.xhostd.com/alice/my-site.git",
  "template": "static",
  "created_at": "2026-04-22T10:30:00Z",
  "external_db_access_enabled": false,
  "external_blob_access_enabled": false,
  "port_forwarding_enabled": false,
  "port_forwarding_available": true,
  "agent_protected_actions_enabled": null,
  "agent_protected_actions_effective": false,
  "channels": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "prod",
      "hostname": "my-site-alice.xhostd.app",
      "git_ref_binding": "branch:master",
      "current_sha": null,
      "status": "provisioning",
      "pending_deploy": null
    }
  ],
  "owner_username": "alice",
  "role": "owner"
}

Errors

Get details of a single app, including all channels.

Auth: Bearer token

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "my-site",
  "repo_url": "https://git.xhostd.com/alice/my-site.git",
  "template": "static",
  "created_at": "2026-04-22T10:30:00Z",
  "external_db_access_enabled": false,
  "external_blob_access_enabled": false,
  "port_forwarding_enabled": false,
  "port_forwarding_available": true,
  "agent_protected_actions_enabled": null,
  "agent_protected_actions_effective": false,
  "channels": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "prod",
      "hostname": "my-site-alice.xhostd.app",
      "git_ref_binding": "branch:master",
      "current_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "status": "running",
      "pending_deploy": null
    }
  ],
  "owner_username": "alice",
  "role": "owner"
}

Errors

Delete an app. Stops all containers, removes the git repo, and cleans up DNS routes.

Auth: Bearer token — requires repo:* scope

curl -X DELETE https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer $XHOST_TOKEN"

Returns 204 No Content on success.

Errors

List all channels for an app.

Auth: Bearer token

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels \
  -H "Authorization: Bearer $XHOST_TOKEN"

[
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "prod",
    "hostname": "my-site-alice.xhostd.app",
    "git_ref_binding": "branch:master",
    "current_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "status": "running",
    "pending_deploy": null
  },
  {
    "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "name": "staging",
    "hostname": "staging-my-site-alice.xhostd.app",
    "git_ref_binding": "branch:staging",
    "current_sha": null,
    "status": "provisioning",
    "pending_deploy": null
  }
]

Create a new channel (e.g., a preview or staging environment).

Auth: Bearer token — requires channel:* scope

Request body

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging", "git_ref_binding": "branch:staging"}'

{
  "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "name": "staging",
  "hostname": "staging-my-site-alice.xhostd.app",
  "git_ref_binding": "branch:staging",
  "current_sha": null,
  "status": "provisioning",
  "pending_deploy": null
}

Errors

Get details of a single channel.

Auth: Bearer token

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "prod",
  "hostname": "my-site-alice.xhostd.app",
  "git_ref_binding": "branch:master",
  "current_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "status": "running",
  "pending_deploy": null
}

Errors

Delete a channel. Stops the container and removes DNS routes. Cannot delete the prod channel.

Auth: Bearer token — requires channel:* scope

curl -X DELETE https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/a3bb189e-8bf9-3888-9912-ace4e6543002 \
  -H "Authorization: Bearer $XHOST_TOKEN"

Returns 204 No Content on success.

Errors

Live built-image inventory for one channel, newest first, plus the per-plan image-size cap. app and docker templates build images; static returns an empty list.

Auth: Bearer token — requires deploy:* scope

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/images \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "images": [
    {
      "tag": "xhost/7c9e6679-7425-40de-944b-e07fc1f90ae7:a1b2c3d",
      "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "size_bytes": 213909504,
      "charged_size_bytes": 41943040,
      "matched_base": "node:22-trixie-slim",
      "created": 1752969600,
      "current": true
    }
  ],
  "image_cap_bytes": 536870912
}

Response fields

Errors

Stream a tar of the channel's code at one checkpoint. With snapshot_id the route serves the commit that snapshot recorded, so the code matches the database of the same checkpoint. Without it the route serves the channel's current commit. For an arbitrary ref use GET /apps/{app_id}/tree instead. Each download is audit-logged.

Auth: Bearer token — requires repo:* scope

Query parameters

curl "https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/code/download?snapshot_id=1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0" \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -o code.tar

Returns 200 OK with Content-Type: application/x-tar and a Content-Disposition attachment header. The body is the tar, streamed.

Errors

Trigger a deploy. Pulls the specified SHA or branch from git, builds the container, and brings it live.

Auth: Bearer token — requires deploy:* scope

Request body

At least one of sha or ref must be provided. If both are given, sha wins and ref is ignored.

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/deploy \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha": "HEAD"}'

{
  "deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "channel_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "queued"
}

Errors

Fetch one deploy's status and a byte window of its build log. Read the outcome from the status field, never from the log text. A queued deploy with no log yet answers 200 with an empty log and log_bytes: 0, not 404.

Auth: Bearer token — requires deploy:* scope

Query parameters

curl "https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/logs?deploy=9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "git_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "status": "success",
  "started_at": "2026-04-22T10:31:00Z",
  "finished_at": "2026-04-22T10:31:03Z",
  "log_bytes": 1207,
  "offset": 0,
  "window_bytes": 1207,
  "log": "[2026-04-22T10:31:00Z] git-sync: resolved HEAD -> a1b2c3d4\n..."
}

status is one of queued, running, success, or failed; poll while it is queued or running. finished_at is null until the deploy finishes. log_bytes is the total size of the log, offset is where the returned window starts, and window_bytes is the byte length of the returned window before utf-8 decoding. The next page starts at offset + window_bytes; when that sum equals log_bytes, the reply reaches the end of the log.

Errors

Read a channel container's stdout/stderr, live or archived. The runtime counterpart of GET .../logs, which covers the build window only. The log is materialized as app.log inside a throwaway, network-less container, and command runs there as a shell pipeline. Omit command and no container starts — the reply carries the status facts alone, which is the "tell me how it died" query. When a redeploy replaces a container, the old container's log is archived, so an older container_index reads why the previous version crashed.

Auth: Bearer token — requires deploy:* scope

Request body

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/runtime/log \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "tail -n 50 app.log"}'

{
  "container_index": 2,
  "container_id": "9c1f8a2b04e7",
  "container_name": "xhost-f47ac10b-7c9e6679-00000002",
  "running": true,
  "source": "live",
  "status": "running",
  "exit_code": null,
  "oom_killed": false,
  "restart_count": 0,
  "started_at": "2026-08-29T09:12:41.183220794Z",
  "finished_at": null,
  "available_indices": [0, 1, 2],
  "log_bytes": 48213,
  "output": "2026-08-29T09:14:02.077410122Z listening on :8080\n...",
  "command_exit_code": 0,
  "timed_out": false,
  "truncated": false
}

exit_code, status, oom_killed, and restart_count describe the logged container — your app. command_exit_code is the query command's own exit code, and is null when no command ran or the sandbox hit the timeout. output is the command's combined stdout and stderr, capped at 256 KiB with truncated: true past the cap. Only stdout/stderr is captured — an app that writes its logs to a file inside the container has nothing here.

Errors

Set (upsert) an environment variable or secret. App-level by default; pass channel_id for a per-channel override. Takes effect on the next deploy.

Auth: Bearer token — requires deploy:* scope

Request body

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/env \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "STRIPE_SECRET_KEY", "value": "sk_live_...", "kind": "secret"}'

Returns 204 No Content on success.

Errors

Delete an environment variable or secret. Takes effect on the next deploy.

Auth: Bearer token — requires deploy:* scope

Query parameters

curl -X DELETE https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/env/STRIPE_SECRET_KEY \
  -H "Authorization: Bearer $XHOST_TOKEN"

Returns 204 No Content on success.

Errors

List an app's environment variables and secrets. Plain values are returned in cleartext; the list returns metadata only for secrets — read a secret's value with GET /apps/{app_id}/env/{key}/value.

Auth: Bearer token — requires deploy:* scope

Query parameters

curl "https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/env?channel_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "env": [
    {
      "key": "MY_VAR",
      "kind": "env",
      "scope": "app",
      "channel_id": null,
      "updated_at": "2026-01-16T10:30:00Z",
      "value": "my-value"
    },
    {
      "key": "STRIPE_SECRET_KEY",
      "kind": "secret",
      "scope": "channel",
      "channel_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "updated_at": "2026-01-16T10:31:00Z",
      "value": null
    }
  ]
}

scope is app (app-level default) or channel (channel override). value is the cleartext for kind: "env" rows and always null for secrets in the list — the read path for a secret's value is GET /apps/{app_id}/env/{key}/value, where each reveal is audit-logged.

Errors

Reveal a single environment value in cleartext — the only read path for kind: "secret". Every call records an env.reveal audit event in the app journal before the value is returned.

Auth: Bearer token — requires deploy:* scope

Query parameters

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/env/STRIPE_SECRET_KEY/value \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "key": "STRIPE_SECRET_KEY",
  "kind": "secret",
  "scope": "app",
  "value": "sk_live_..."
}

Errors

Return the env snapshot recorded when a deploy started — what the app actually ran with, independent of edits made since.

Auth: Bearer token — requires deploy:* scope

{
  "deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "env": [
    {"key": "MY_VAR", "kind": "env", "source": "app", "value": "my-value"},
    {"key": "STRIPE_SECRET_KEY", "kind": "secret", "source": "channel", "value": null}
  ],
  "system_keys": ["DATABASE_URL", "XHOST_SHA", "XHOST_USER"]
}

source is the scope the value resolved from (app or channel). Secret values are masked (null); system-injected keys are listed by name only — their values are credentials and are not stored in the snapshot.

Errors

Attach a custom domain. Returns the DNS records you must create at your registrar before calling /verify.

Auth: Bearer token

Request body

{
  "domain": "app.customer.com",
  "status": "pending",
  "reason": null,
  "dns_records": {
    "txt_host": "_xhost.app.customer.com",
    "txt_value": "xhost-verify-abcdef0123456789abcdef0123456789",
    "cname_target": "prod-blog-alice.xhostd.app",
    "a_values": ["198.51.100.7"]
  },
  "created_at": "2026-06-12T00:00:00Z",
  "verified_at": null
}

Errors

List every custom domain attached to a channel. Same per-item shape as POST.

Auth: Bearer token

{"domains": [{...}, {...}]}

Re-check the DNS records for an attached domain. Idempotent and retryable — DNS propagation usually takes a few minutes.

Auth: Bearer token

On a passing check, status flips from pending to verified and the public route + on-demand TLS go live. A verified domain only downgrades on the four definitive reasons (txt_nxdomain, txt_token_mismatch, dns_not_pointing, domain_nxdomain); transient resolver failures (txt_lookup_failed, dns_lookup_failed, platform_ip_unknown) are recorded as reason but never downgrade.

{
  "domain": "app.customer.com",
  "status": "verified",
  "reason": null,
  "dns_records": { ... },
  "created_at": "2026-06-12T00:00:00Z",
  "verified_at": "2026-06-12T00:05:00Z"
}

Detach a custom domain. The route is removed immediately; certificate renewals stop.

Auth: Bearer token

{"ok": true}

Inspect the channel's Postgres database: name, role, status, live connection count, storage usage.

Auth: Bearer token

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "db_name": "ch_7c9e6679742540de944be07fc1f90ae7",
  "role_name": "r_7c9e6679742540de944be07fc1f90ae7",
  "status": "ready",
  "last_error": null,
  "connection_count": 2,
  "connection_limit": 20,
  "password_set": true,
  "storage_bytes": 81920
}

Response fields

Errors

Empty the channel's database. The role and password are preserved, so the same DATABASE_URL keeps working.

Auth: Bearer token

Request body

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres/reset \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm_db_name": "ch_7c9e6679742540de944be07fc1f90ae7"}'

Returns 204 No Content on success.

Errors

Stream a pg_dump of the channel's database. That channel's data and nothing else. Useful for backups and migrating data between channels. Each dump is audit-logged.

Auth: Bearer token

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres/dump \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -o channel.sql

Returns 200 OK with Content-Type: application/sql and a Content-Disposition attachment header. The body is the raw pg_dump output, streamed.

Errors

List the channel's Postgres snapshots of every kind, newest first. xhostd takes one automatically before each deploy (kind pre_deploy) and one per day (kind nightly).

Auth: Bearer token

[
  {
    "snapshot_id": "1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0",
    "deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "created_at": "2026-07-20T09:12:00Z",
    "git_sha": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a"
  }
]

git_sha names the commit this snapshot belongs to. On a pre_deploy snapshot it is the commit that ran before the deploy, because the snapshot holds the state that commit left. It is null when xhostd recorded no commit for the row. A null is a state, not a fault: that row simply has no code leg. Pass the id of this row as snapshot_id to GET .../code/download to fetch the matching code.

Errors

Mint a short-lived snapshots:read token for one owned snapshot. The calling token must carry snapshots:read itself, because a mint never grants more than the caller already holds. The plaintext is returned once and expires in one hour. A general credential already reaches the download URL, because snapshots:read is default-granted; mint this when you want a single-purpose token instead.

Auth: Bearer token carrying snapshots:read

{
  "token": "xh_snap123...",
  "download_url": "/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres/snapshots/1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0/download",
  "expires_at": "2026-07-24T10:05:00Z"
}

Errors

Stream one snapshot's archive. The archive is a complete custom-format pg_dump, so pg_restore reads it directly. To put the snapshot back into the channel's own database, use POST .../postgres/restore instead. Each download is audit-logged.

Auth: Bearer token — requires snapshots:read scope (mint via download-token)

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres/snapshots/1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0/download \
  -H "Authorization: Bearer $DOWNLOAD_TOKEN" \
  -o snapshot.sqlc

Returns 200 OK with Content-Type: application/octet-stream and a Content-Disposition attachment header. The body is the snapshot archive, streamed.

Errors

Restore the channel's database from a snapshot of either kind, replacing current data. Restoring the prod channel is blocked unless the app has the env var XHOST_ALLOW_PROD_RESTORE=1. Each restore is audit-logged.

Auth: Bearer token

Request body

curl -X POST https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/postgres/restore \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm_db_name": "ch_7c9e6679742540de944be07fc1f90ae7", "snapshot_id": "1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0"}'

Returns 200 OK with the channel's Postgres status (same shape as GET .../postgres).

Errors

Report total Postgres storage and database count for the authenticated user, across all channels.

Auth: Bearer token

curl https://api.xhostd.com/me/postgres/storage \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "database_size_bytes": 1572864,
  "database_count": 5
}

Response fields

Errors

Inspect the channel's object store: provisioning status, usage, and the virtual S3 endpoint/bucket the app sees.

Auth: Bearer token

{
  "status": "ready",
  "last_error": null,
  "usage_bytes": 10485760,
  "external_enabled": false,
  "virtual_bucket": "my-site-alice-xhostd-com",
  "virtual_endpoint": "https://my-site-alice.s3.xhostd.app",
  "region": "xhost"
}

Errors

Return the channel's S3-compatible credentials — the only payload carrying the secret key. Each call is audit-logged.

Auth: Bearer token — requires blob:* scope

{
  "access_key_id": "AKxhost...",
  "secret_access_key": "…",
  "endpoint": "https://my-site-alice.s3.xhostd.app",
  "region": "xhost",
  "bucket": "my-site-alice-xhostd-com"
}

Errors

List the channel's object-store snapshots of every kind, newest first. xhostd marks one before each deploy (kind pre_deploy) and one per day (kind nightly).

Auth: Bearer token

[
  {
    "snapshot_id": "2a1b0c9d-8e7f-6a5b-4c3d-2e1f0a9b8c7d",
    "deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "snapshot_ts": "2026-07-20T09:11:58Z",
    "created_at": "2026-07-20T09:12:00Z",
    "pg_snapshot_id": "1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0"
  }
]

pg_snapshot_id names the Postgres snapshot of the same checkpoint, so the two legs hold one instant. It is null when the two passes did not align. The two prunes run on their own, so the id can also name a Postgres row that no longer exists. Both cases mean the same thing: the two legs are not aligned. Neither is a fault.

Errors

Mint a short-lived blobs:read token for one owned checkpoint. The calling token must carry blobs:read itself, because a mint never grants more than the caller already holds. The snapshot_id is the Postgres checkpoint id; the route resolves the aligned blob leg from it. The plaintext is returned once and expires in one hour. A general credential already reaches the download URL, because blobs:read is default-granted; mint this when you want a single-purpose token instead.

Auth: Bearer token carrying blobs:read

{
  "token": "xh_blob123...",
  "download_url": "/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/blob/snapshots/1f0e2d3c-4b5a-6978-8796-a5b4c3d2e1f0/download",
  "expires_at": "2026-07-24T10:05:00Z"
}

Errors

Stream the channel's objects as they were at the checkpoint's instant, as one tar. The snapshot_id is the Postgres checkpoint id; xhostd resolves the aligned blob leg and reads the object versions live at that instant, so the tar holds what POST .../blob/restore would put back. Each download is audit-logged.

Auth: Bearer token — requires blobs:read scope (mint via download-token)

curl https://api.xhostd.com/apps/f47ac10b-58cc-4372-a567-0e02b2c3d479/channels/7c9e6679-7425-40de-944b-e07fc1f90ae7/blob/snapshots/2a1b0c9d-8e7f-6a5b-4c3d-2e1f0a9b8c7d/download \
  -H "Authorization: Bearer $DOWNLOAD_TOKEN" \
  -o files.tar.gz

Returns 200 OK with Content-Type: application/gzip and a Content-Disposition attachment header. The body is the tar, streamed.

Errors

Restore the channel's object-store prefix to a checkpoint's point-in-time, replacing current objects. The snapshot_id is the checkpoint id from GET .../postgres/snapshots whose aligned_blob flag is true; the route resolves the aligned blob leg from it. Restoring the prod channel is blocked unless the app has the env var XHOST_ALLOW_PROD_RESTORE=1. Each restore is audit-logged.

Auth: Bearer token

Request body

Returns 200 OK with the channel's blob status (same shape as GET .../blob).

Errors

Report total object-store usage and provisioned store count for the authenticated user, across all channels.

Auth: Bearer token

{
  "blob_usage_bytes": 10485760,
  "store_count": 3
}

Generate a read-only Ed25519 deploy key and record the remote. Does not fetch — add the returned public key as a deploy key on GitHub, then call /github/sync.

Auth: Bearer token — requires the owner role on the app

Request body

{
  "public_key": "ssh-ed25519 AAAA... xhost-deploy-f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "remote_url": "git@github.com:alice/my-site.git"
}

Errors

Connection status and last sync outcome. connected: false (other fields null) when no repo is connected.

Auth: Bearer token

{
  "connected": true,
  "remote_url": "git@github.com:alice/my-site.git",
  "public_key": "ssh-ed25519 AAAA...",
  "connected_at": "2026-07-01T08:00:00Z",
  "last_synced_at": "2026-07-20T09:11:00Z",
  "last_sync_status": "ok",
  "last_sync_error": null,
  "last_sync_refs": {"refs/heads/master": "a1b2c3d4..."}
}

Errors

Fetch the connected remote into the app's internal repo. Returns the updated status; inspect last_sync_status for the outcome.

Auth: Bearer token — requires the admin role on the app

Errors

Disconnect the GitHub repo and discard the deploy key. The app's internal repo and deploy history are unchanged.

Auth: Bearer token — requires the owner role on the app

Returns 204 No Content on success.

Errors

Open a starter account for the holder of an Ed25519 key. The response holds a 30-day default-scope token, and the key is registered on the account with api_login, so it renews the token through POST /auth/ssh-key and pushes over SSH with no further call.

Auth: none. The signed message is the proof.

Request body

Any other field answers 422.

xhostd-register
<username or empty>
<timestamp>

curl -sS https://api.xhostd.com/registrations \
  -H "Content-Type: application/json" \
  --data @body.json -o response.json -w 'HTTP %{http_code}\n'

{
  "user_id": "3f1c2a7e-9b4d-4c1e-8a6f-2d5b7c9e0f13",
  "username": "agent7k2m9x4q",
  "plan": "starter",
  "token": "xh_...",
  "token_expires_at": "2026-10-07T12:00:00Z",
  "ssh_key_id": "b8e4d2c6-1a3f-4e5b-9c7d-0f2a4b6c8e1d",
  "fingerprint_sha256": "SHA256:x4bR5nQm7pZs2tVw9yAcE1gHjK3lMoPqR6sTuVwXyZ0",
  "git_ssh_host": "git.xhostd.com",
  "limits": { "tier": "starter", "max_channels": 1, "blob_storage_bytes": 134217728, "...": "..." },
  "next": { "verify_email": "POST /me/email-verifications", "renew_token": "POST /auth/ssh-key" }
}

Errors

Mint a fresh 30-day default-scope token for a key registered with api_login: the registration key, or a key POST /ssh-keys stored with api_login true. An account holds at most 20 tokens from this route.

Auth: none. The signed message is the proof.

Request body

xhostd-login
<fingerprint_sha256>
<timestamp>

curl -sS https://api.xhostd.com/auth/ssh-key \
  -H "Content-Type: application/json" \
  --data @body.json -o response.json -w 'HTTP %{http_code}\n'

{
  "token": "xh_...",
  "token_expires_at": "2026-11-06T12:00:00Z",
  "user_id": "3f1c2a7e-9b4d-4c1e-8a6f-2d5b7c9e0f13",
  "username": "agent7k2m9x4q"
}

Errors

Create a new API token for the authenticated user. The new token carries the full default scope set, so the token you call with must carry it too — a mint never grants more than the caller already holds. To mint from a narrower token, use POST /credentials, which grants the scopes you hold or fewer.

Auth: Bearer token carrying all nine default scopes

Request body

curl -X POST https://api.xhostd.com/tokens \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci"}'

{
  "token_id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "plaintext": "xh_newtoken123...",
  "scopes": ["repo:*", "deploy:*", "channel:*", "db:*", "blob:*", "stats:read", "exports:read", "snapshots:read", "blobs:read"],
  "label": "ci",
  "created_at": "2026-04-22T11:00:00Z",
  "expires_at": null
}

Errors

Revoke a token. The token is immediately invalidated.

Auth: Bearer token

curl -X DELETE https://api.xhostd.com/tokens/c56a4180-65aa-42ec-a945-5fd21dec0538 \
  -H "Authorization: Bearer $XHOST_TOKEN"

Returns 204 No Content on success.

Errors

Mint a unified credential. The returned token serves as your git password, Postgres password, object-storage and download credential, and platform API bearer. It lives 30 days unless you pass a shorter expires_in. A mint never grants more than the caller already holds, so this route grants the default scopes your calling token carries, or the subset you name within them.

Auth: Bearer token

Request body (optional)

curl -X POST https://api.xhostd.com/credentials \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "token": "xh_abc123...",
  "username": "alice",
  "expires_at": "2026-05-22T11:00:00Z",
  "scopes": ["repo:*", "deploy:*", "channel:*", "db:*", "blob:*", "stats:read", "exports:read", "snapshots:read", "blobs:read"]
}

To push over git, put the token in the password field of the remote URL — https://<username>:<token>@git.xhostd.com/<username>/<app>.git (any username works; the password is what is checked). git.xhostd.com also accepts the token via Authorization: Bearer. Re-mint after the 30-day expiry.

Errors

Register one OpenSSH public-key line on the caller's account. The platform notifies the user about the new key, with its label and fingerprint. A key reaches every repository on the account, so the calling token must carry repo:*; api_login asks for all nine default scopes, because that is what the key goes on to mint.

Auth: Bearer token carrying repo:*

Request body

Any other field answers 422.

curl -X POST https://api.xhostd.com/ssh-keys \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/xhost_ed25519.pub)\", \"label\": \"claude-code\"}"

{
  "id": "b8e4d2c6-1a3f-4e5b-9c7d-0f2a4b6c8e1d",
  "label": "claude-code",
  "algo": "ssh-ed25519",
  "fingerprint": "SHA256:x4bR5nQm7pZs2tVw9yAcE1gHjK3lMoPqR6sTuVwXyZ0",
  "created_at": "2026-08-17T10:30:00Z",
  "last_used_at": null,
  "api_login": false
}

Then push: git remote add xhost-ssh "git@git.xhostd.com:<username>/<app>.git" and GIT_SSH_COMMAND="ssh -i ~/.ssh/xhost_ed25519 -o IdentitiesOnly=yes" git push xhost-ssh HEAD:master.

Errors

List the caller's SSH keys, newest first. Metadata only.

Auth: Bearer token

curl https://api.xhostd.com/ssh-keys \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "ssh_keys": [
    {
      "id": "b8e4d2c6-1a3f-4e5b-9c7d-0f2a4b6c8e1d",
      "label": "claude-code",
      "algo": "ssh-ed25519",
      "fingerprint": "SHA256:x4bR5nQm7pZs2tVw9yAcE1gHjK3lMoPqR6sTuVwXyZ0",
      "created_at": "2026-08-17T10:30:00Z",
      "last_used_at": null,
      "api_login": false
    }
  ]
}

last_used_at is null while the key served no git command yet. api_login is true for a key that can sign in through POST /auth/ssh-key.

Delete one SSH key the caller owns. The delete is the whole revoke, so a push with that key fails at once.

Auth: Bearer token

curl -X DELETE https://api.xhostd.com/ssh-keys/b8e4d2c6-1a3f-4e5b-9c7d-0f2a4b6c8e1d \
  -H "Authorization: Bearer $XHOST_TOKEN"

Returns 204 No Content on success.

Errors

Start one email challenge. The platform mails an 8-character code (lowercase letters and digits without 0, 1, i, l, o) that expires in 15 minutes. A new request after 60 seconds replaces the code.

Auth: Bearer token

Request body

curl -X POST https://api.xhostd.com/me/email-verifications \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "owner@example.com"}'

{
  "status": "sent",
  "expires_at": "2026-09-07T12:15:00Z"
}

Errors

Prove the code. Success writes the address as the account's sign-in email, moves a starter account to basic, and queues the plan apply that raises the limits.

Auth: Bearer token

Request body

curl -X POST https://api.xhostd.com/me/email-verifications/complete \
  -H "Authorization: Bearer $XHOST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "abcd2345"}'

{
  "status": "verified",
  "plan": "basic",
  "apply_queued": true
}

apply_queued is false when a move holds the account; the apply runs after it.

Errors

Submit free-text feedback to the xhostd team about platform friction. Attributed to the authenticated user. Fire-and-forget.

Auth: Bearer token

Request body

{
  "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
  "status": "Received"
}

Errors

List the authenticated user's feedback reports, newest first, each with the xhostd team's answers. One call answers one page of the account's reports, whichever surface filed them.

Auth: Bearer token

Query parameters

{
  "reports": [
    {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "message": "Deploy logs don't stream.",
      "status": "Resolved",
      "source": "agent",
      "app_name": "myapp",
      "created_at": "2026-01-04T10:00:00+00:00",
      "handled_at": "2026-01-05T09:30:00+00:00",
      "messages": [
        {
          "body": "Status changed to Resolved.\n\nStreaming logs shipped today.",
          "created_at": "2026-01-05T09:30:00+00:00",
          "status": "Resolved"
        }
      ]
    }
  ],
  "next_cursor": "MjAyNi0wMS0wNFQxMDowMDowMCswMDowMHxjNTZhNDE4MC02NWFhLTQyZWMtYTk0NS01ZmQyMWRlYzA1Mzg"
}

status is one of Received, Resolved or Closed. source is agent or console. app_name is null when the report carries no app context. messages holds the team's answers oldest first; a message carries a status only when it records a status change. Internal team notes are never listed. next_cursor is an opaque value: pass it as cursor to read the next page, and it is null when the account has no older report.

Get dashboard statistics for the authenticated user. The counts and the sites rows cover every project the caller can see, shared projects included — a repo value reads owner/project. The resources block is the caller's own memory and CPU alone, because a shared project runs under its owner's resource slice.

Auth: Bearer token — requires stats:read scope

curl https://api.xhostd.com/api/user/stats \
  -H "Authorization: Bearer $XHOST_TOKEN"

{
  "username": "alice",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": {
    "apps": 3,
    "channels": 5,
    "running_channels": 4,
    "deploys_last_hour": 1,
    "deploys_last_day": 7,
    "success_last_day": 6,
    "failed_last_day": 1
  },
  "resources": {
    "mem_current_mb": 45.2,
    "mem_limit_mb": 128.0,
    "mem_percent": 35.3,
    "cpu_current_percent": 2.5
  },
  "sites": [
    {
      "hostname": "my-site-alice.xhostd.app",
      "repo": "alice/my-site",
      "branch": "master",
      "status": "running",
      "sha": "abc1234",
      "latest_deploy_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "latest_deploy_status": "success"
    }
  ],
  "collected_at": "2026-04-24 10:30:00 UTC"
}

Response fields

Per-account database storage and current-month egress. Storage is a soft cap — over-limit warns, it never blocks. Egress carries no limit field, because no plan states an egress figure: the platform measures egress, reports it, and charges nothing for it.

Auth: Bearer token

{
  "plan": "basic",
  "storage_bytes": 1572864,
  "storage_limit_mb": 250,
  "bandwidth_month_bytes": 104857600
}

Errors

Every plan tier and the caps it grants, lowest rank first. No row states an egress figure, because no plan limits egress. This is the one published source of a plan number: the console, the docs and the agent tools all read it rather than holding a constant. The response carries no price — billing lives at Lemon Squeezy.

Auth: none. The route is public, reads no database, and returns the same body for every caller.

{
  "plans": [
    {
      "tier": "basic",
      "rank": 0,
      "max_channels": 5,
      "cpu_soft_cores": 0.1,
      "cpu_burst": 2,
      "visible_cores": 1,
      "mem_limit_mb": 128,
      "storage_mb": 250,
      "blob_storage_bytes": 1073741824,
      "image_size_bytes": 536870912,
      "snapshot_retention_days": 1,
      "deploy_snapshot_keep": 1,
      "port_forwarding": false
    }
  ]
}

Response fields

Aggregated traffic statistics for one channel: requests and unique visitors by hour, status-class breakdown, top pages/404s/assets, hour-of-day distribution, and country breakdown.

Auth: Bearer token — requires stats:read scope

Query parameters

{
  "range": "24h",
  "finalized_through": "2026-07-21T00:00:00Z",
  "requests_by_hour": [{"t": "2026-07-21T09:00:00Z", "hits": 42}],
  "status_breakdown": {"2xx": 400, "3xx": 12, "4xx": 7, "5xx": 0},
  "top_pages": [{"path": "/", "hits": 180}],
  "top_404s": [{"path": "/favicon.png", "hits": 3}],
  "top_assets": [{"path": "/style.css", "hits": 170}],
  "unique_visitors_by_hour": [{"t": "2026-07-21T09:00:00Z", "unique_visitors": 17}],
  "hour_of_day_distribution": [{"hour": 9, "hits": 42}],
  "country_breakdown": [{"country_code": "US", "hits": 210, "unique_visitors": 40}],
  "country_totals": {"hits": 260, "unique_visitors": 55, "countries": 12}
}

finalized_through is the start of the current UTC day; buckets at or after it are still mutable (the live edge). country_code may be null when the lookup missed.

country_breakdown holds the top 10 countries, ranked by unique_visitors descending, then hits descending, then country_code. The country_code: null (Unknown) row is not ranked: it always follows the ranked countries, so the list may hold 11 entries. country_totals covers every country in the window and is the denominator of that list. Its unique_visitors is the SUM of the per-country distinct counts, not one distinct count over the window, so a visitor seen in two countries counts twice.

Errors

Aggregated traffic statistics summed across all of an app's channels. Same shape and range semantics as the per-channel stats endpoint.

Auth: Bearer token — requires stats:read scope

Errors

Attributed activity trail of project mutations (member changes, deploys, env writes and reveals, database operations, git pushes), newest first. No secret values appear. Any member can read.

Auth: Bearer token

Query parameters

{
  "events": [
    {
      "id": "uuid",
      "actor_username": "alice",
      "action": "deploy.create",
      "target": "prod",
      "detail": {},
      "created_at": "2025-01-16T10:30:00Z"
    }
  ],
  "next_before": "2025-01-16T10:30:00Z"
}

next_before is null when there are no more events; otherwise pass it as before to fetch the next page. actor_username is null for system actions.

Queue an export. Returns 202 with the export row; poll GET /exports/{export_id} for progress.

Auth: Bearer token

Request body

{
  "id": "5d41402a-bc4b-4a2a-8b8e-1327dd93b5b1",
  "scope": "channel",
  "app_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "channel_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "queued",
  "detail": null,
  "progress_pct": 0,
  "size_bytes": null,
  "error": null,
  "blobs_included": false,
  "blobs_reason": null,
  "blob_object_count": null,
  "blob_bytes_estimate": null,
  "created_at": "2026-07-21T10:00:00Z",
  "finished_at": null,
  "expires_at": null
}

Errors

List the authenticated user's exports, newest first. GET /exports/{export_id} returns a single row (404 if not yours). Rows use the same shape as the create response; a ready export carries size_bytes, expires_at, and the blob-inclusion fields.

Auth: Bearer token

Mint a short-lived exports:read token for a ready, owned export. The calling token must carry exports:read itself, because a mint never grants more than the caller already holds. The plaintext is returned once and expires with the export. Use it as the bearer on the download URLs.

Auth: Bearer token carrying exports:read

{
  "token": "xh_export123...",
  "download_url": "/exports/5d41402a-bc4b-4a2a-8b8e-1327dd93b5b1/download",
  "blobs_download_url": "/exports/5d41402a-bc4b-4a2a-8b8e-1327dd93b5b1/download/blobs",
  "expires_at": "2026-07-24T10:05:00Z",
  "blobs_included": true,
  "blobs_reason": null
}

Errors

Stream the export.tar.gz archive. GET /exports/{export_id}/download/blobs streams blobs.tar.gz with the object-store contents pinned to the versions inventoried at build time. Each download is audit-logged.

Auth: Bearer token — requires exports:read scope (mint via download-token)

curl https://api.xhostd.com/exports/5d41402a-bc4b-4a2a-8b8e-1327dd93b5b1/download \
  -H "Authorization: Bearer $DOWNLOAD_TOKEN" \
  -o export.tar.gz

Errors