Gateway, APIs, and MCP

There are two doors. A public read door for site content. A worker door for Requests on one site. MCP wraps the same worker verbs for interactive agents. Call HTTP for headless work.

Public read API

The public API serves tenant-scoped pages, blog posts, site settings, and entities. It can require a public runtime key and is rate limited. It is not the worker door. Do not send a worker key as a public key.

Runtime API keys

Admin or developer mints a Runtime key on API Keys, in the first-login wizard, or from GET and POST /api/developer/v1/runtime-keys. reuse defaults true. The raw key is shown once. The wizard and API Keys also show the Connect your agent line Set up my xTerminal site and the setup skill at /xterminal/skills/setup-site/v1. Worker keys cannot call the Runtime door.

Worker door

The worker door is /api/worker/v1. It is not a GitHub or host proxy. Admin or developer mints the key under Settings, Requests. Owners never see that form.

Auth

• Send Authorization: Bearer and the raw key, or the x-xt-worker-key header.
• One key per site. A worker may hold several keys. Never share one key across sites.
• A revoked key cannot act. Fail closed if Requests is not on for that site.

What you can call

• GET /api/worker/v1/workspace: slug, name, linked repo as context, access.
• GET /api/worker/v1/requests: list, filter open, shipped, or all.
• GET /api/worker/v1/requests/{id}: developer-shaped detail, events, attachments.
• POST /api/worker/v1/requests/{id}/events: a comment. Actor is agent.
• PATCH /api/worker/v1/requests/{id}: status, preview, delivery, and related fields.

How to call it

1. Mint a worker key on the site. Copy it once.
2. Read workspace context, then list open Requests.
3. On a new Request, pick it up before any other status.
4. When proof is complete, send preview plus delivery and move to Review.
5. After Ship to live, mark shipped. The product rejects shipped too early.

Wake webhook

Optional. Admin or developer saves an HTTPS URL and a shared secret on Settings, Requests. Sitedio POSTs a small JSON wake with Authorization: Bearer. Fail soft. Each site keeps its own URL.

MCP

Interactive agents register /api/mcp over streamable HTTP, then sign in with OAuth 2.1 and PKCE. The first verified tools read workspace context and Requests. Write tools beyond that read set come later. Worker keys stay the headless door. See Connect an agent (MCP).

What never goes in the key

• A second site's Requests.
• Billing, Team invites, or transfer.
• Secrets stored as Knowledge Base integrations notes.
• A bot brand name in the dashboard or in owner-facing copy.