xTerminal

Docs

Gateway, APIs, and MCP

How a worker reads and calls this site. HTTP is live. MCP packaging is Coming soon. No bot brand names.

Coming soon on the longer handbook. What follows is the live surface, not a promised catalog.

There are two doors. A public read door for site content. A worker door for Requests on one site. MCP is a later wrapper around those HTTP verbs. Call HTTP today.

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.

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. xTerminal POSTs a small JSON wake with Authorization: Bearer. Fail soft. Each site keeps its own URL.

MCP

Coming soon: an MCP wrapper that exposes the same worker verbs, with OAuth for interactive agents. Until that ships, there is no MCP connector to install from this dashboard. Call the HTTP 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.