Runner API reference

These are the public cloud endpoints your self-hosted runner process calls. Set RUNNER_API_BASE on the worker to match your deployment (same host as below).

Credentials (don't mix these up)

Runner API key — secret shown once when you create a runner in Studio (or returned as runnerToken from createRunnerInstance). Format for workers: credentialId.secret. Use this as Authorization: Bearer … for lease, heartbeat, context, complete, and fail. It is not your login password and not your Firebase session.
Studio account token (Firebase ID token) — only for creating, renaming, or revoking runner instances via the API (same actions as Settings → Runners in the app). Send Authorization: Bearer with the Firebase ID token for the signed-in user. Your worker should never use this token to dequeue or complete jobs.

Base URL

All paths below are HTTPS functions on: https://cloud.xenonflare.com

See Runners & queues for pools, keys, and how jobs are targeted. JSON request and response bodies use Content-Type: application/json unless noted.

Managing runner instances (Studio account)

Same operations as Settings → Runners. Use a Firebase ID token (Bearer) only on these three routes — not for the job loop below.

POSThttps://cloud.xenonflare.com/createRunnerInstance

Create runner instance (credential)

Auth: Bearer: Firebase ID token (signed-in Studio user). Body: { "kind": "user"|"global", "name"?: string }. Global requires admin doc admins/<uid>.

201 — { instanceId, credentialId, runnerToken, kind, name }. The field runnerToken is the Runner API key; store it once — it won't be shown again.

POSThttps://cloud.xenonflare.com/revokeRunnerInstance

Revoke runner instance

Auth: Bearer: Firebase ID token. Body: { "instanceId" }.

200 — { "ok": true }

POSThttps://cloud.xenonflare.com/updateRunnerInstance

Rename runner instance

Auth: Bearer: Firebase ID token. Body: { "instanceId", "name" }.

200 — { "ok": true, "name" }

Job lifecycle (Runner API key)

Use the Runner API key only — the value returned as runnerToken when the instance was created, formatted as credentialId.secret in the Authorization: Bearer header (see the open-source runner README).

POSThttps://cloud.xenonflare.com/leaseWorkspaceJob

Lease next pending job

Auth: Bearer: Runner API key (credentialId.secret).

Body: (empty object).

200 — either { "leased": false } or { "leased": true, "workspaceId", "leaseExpiresAt", "workspace": { ... } }. Global instances only see target: "global" jobs; user instances only jobs for that owner with target: "user".

POSThttps://cloud.xenonflare.com/heartbeatWorkspaceJob

Extend job lease (long-running generation)

Auth: Bearer: Runner API key.

Body: { "workspaceId" }

200 — { "ok": true, "leaseExpiresAt": <ms> }

409 — no active lease for this workspace/instance.

POSThttps://cloud.xenonflare.com/getWorkspaceRunnerContext

Load model input context for leased workspace

Auth: Bearer: Runner API key.

Body: { "workspaceId" }

Returns compiled chat + workspace fields for the runner (large JSON). Requires an active lease.

POSThttps://cloud.xenonflare.com/updateWorkspaceRunnerSummary

Persist prior history summary (optional compression step)

Auth: Bearer: Runner API key.

Body:

{
  "workspaceId",
  "summaryText": "<string, large cap>",
  "fromMessageId": "<message id>",
  "throughMessageId": "<message id>"
}

Requires active lease. Used when the runner summarizes older messages before generation.

POSThttps://cloud.xenonflare.com/completeWorkspaceJob

Complete job with deliverables

Auth: Bearer: Runner API key.

Body (JSON): includes workspaceId, assistantMessage (narrative, may include {{artifact:...}} placeholders), and arrays files, charts, datasets (tables), lists, checklists, svgs as produced by the worker. See Deliverables for shapes and caps.

400 — validation error on any payload slice.

POSThttps://cloud.xenonflare.com/failWorkspaceJob

Mark job failed

Auth: Bearer: Runner API key.

Body: { "workspaceId", "error": "<short string>" }

200 — { "ok": true } on success.

← Deliverables & artifacts·Runners & queues