docs(api): Runs, Workspaces and platform tokens in the API reference

[sre-helmcode]

Dependencies deployed and verified in prod (2026-10-10): cloud-api 0.8.238 (#324, a foreign workspace uuid answers the same 404 as an unknown one), cloud-api 0.8.239 (#325, GET /api/workspaces/{uuid} accepts sk- keys and platform tokens), nan-devops #805 (only GET /api/workspaces, /api/workspaces/ and /api/workspaces/{lowercase uuid} reach origin on api.nan.builders; bearer only, no CORS). Ready to merge after review.

What

Moves the Agent runs API out of the guide and into the API reference (/docs/api, /es/docs/api, rendered by Scalar from src/data/openapi.json), and adds the read-only Workspaces endpoints and platform tokens to it.

src/data/openapi.json

• Runs tag (on the default https://api.nan.builders/v1 server):

  • POST /runs (create): body CreateRunRequest with workspace (name or id), agent (pi | hermes), prompt (1 to 32768 bytes), cwd (default /home/nan), git_isolation (null | true | false), timeout_seconds (60..7200, default 1800), model, trigger. Optional Idempotency-Key header. Responses: 201, 200 replay, 400, 401, 403 (tier_restricted, workspace_key_not_allowed), 404, 409 (workspace_not_running, agent_not_installed, no_inference_key, idempotency_conflict), 429 (run_queue_full, rate_limited).
  • GET /runs (filters workspace, state, limit 1..100 default 20, cursor; list object with next_cursor).
  • GET /runs/{id}.
  • GET /runs/{id}/events:
    • text/event-stream: run_event / state / end frames, : hb every 15 s, Last-Event-ID resume, 30-minute stream lifetime, 10 streams per member (429 too_many_streams).
    • application/json pages: after, limit 1..1000 default 500, next_after, done.
  • POST /runs/{id}/cancel (202, or 200 when the run had already ended).

• Schemas: Run, RunResult, RunArtifact, RunList, RunEvent (10 types, data as a oneOf of per-type schemas; message = incremental chunks with final on the last), RunEventPage, CreateRunRequest, Workspace, WorkspaceDetail, WorkspaceSlot, PlatformError. Errors on /v1/runs use the existing OpenAI Error envelope.

• Workspaces tag: only the two public routes (path-level server https://api.nan.builders, outside /v1):

  • GET /api/workspaces: member API key or platform token.
  • GET /api/workspaces/{id}: platform token only (cloud-api accepts sk- keys on the exact list path only).

  Both say only the caller's own workspaces are returned. No session-only workspace route is documented.

• Security:

  • The API key scheme is renamed bearerAuth to apiKey (the name Scalar shows in its selector), and its description is updated. It stays the global default, so inference operations take the API key only.
  • New platformToken scheme (nan_pat_..., platform API only, refused for inference).
  • Runs operations accept both. The overview gains a short "Platform tokens" section.

• Sources (cloud-api origin/main):

  • internal/runs/api.go: limits, states, codes.
  • internal/runs/protocol: event kinds and data, regexes, error codes.
  • internal/handlers/runs.go and runs_sse.go: routes, body, statuses, frames.
  • internal/handlers/workspace.go and internal/workspace/models.go: the workspace view.
  • internal/middleware/auth.go and handlers.PlatformTokenAPIRoutes (#323), plus the /api group's AcceptAPIKeysOn in cmd/server/main.go.

Guide (src/content/docs/runs.mdx, docs-es/runs.mdx)

• The API section keeps the API keys vs tokens explanation and one end-to-end example: create with curl, keep the id with jq, follow with curl -N.
• It links to /docs/api#tag/runs, #tag/workspaces and #description/platform-tokens (or the /es/docs/api equivalents). I checked these anchor formats in the browser: Scalar sets #tag/runs when you click the tag, and both locales scroll to it.
• The endpoint, field, error and stream tables are removed from the guide. The portal and CLI sections are unchanged.

Workspaces contract (after #324, #325, #805)

• Both operations accept an API key or a platform token; the key inside a workspace gets 401 session_required.
• GET /api/workspaces/{id}: a foreign workspace and an unknown id answer the same 404 {"error":"workspace not found"}; a non-UUID id is a 404 from the edge (OpenAI shape). No 403 documented.
• 401 examples are the real /api Auth bodies: {"error":"unauthorized"}, {"error":"invalid session"}, session_required (pinned by tests).
• Each operation notes that api.nan.builders serves it to bearer credentials only, with no cookies and no browser CORS.
• A platform token on inference: /v1/models answers 403 token_scope_denied, /v1/chat/completions answers 401 from the gateway; the scheme says "401, or 403 token_scope_denied".

Tests

• src/lib/openapiSpec.test.ts: the surface list now counts operations (11 inference + 5 runs + 2 workspaces), so an undocumented or extra one fails.
• New src/lib/openapiRuns.test.ts (no OpenAPI validator among the dependencies, so it includes a small JSON Schema validator) checks:
  • tags and operationIds;
  • which operation takes which credential;
  • the body fields, limits and defaults;
  • every error code;
  • the Run, RunEvent and page shapes;
  • the SSE frames, heartbeat, resume, lifetime and stream cap;
  • that the workspace routes are on api.nan.builders with nothing else under /api, and that no secret fields are present;
  • every new example against its schema (the validator is tested on bad input too);
  • that the /api/docs text includes the new operations;
  • no em-dashes.
• src/tests/layouts/runsDocs.test.ts:
  • the guide keeps the create + follow example;
  • its JSON is accepted by the reference schema;
  • it links to the reference;
  • the long tables are gone;
  • the reference contains the runs operations.
• npx vitest run: 1699 tests passed. npm run build: complete.
• Browser (dev server): /docs/api and /es/docs/api show the Runs tag with all 5 operations and the Workspaces tag with 2, and the auth selector offers apiKey and platformToken. /api/docs/api.md includes the new operations.

🤖 Generated with Claude Code

[sre-helmcode]

Blocking reviews (Opus, foreground): QA APPROVED and UX APPROVED at head 939457a (after fixes for QA blockers at 696c2eb and UX blockers at 696c2eb/c06efcf). Merge only after the DevOps exposure of GET /api/workspaces[/{uuid}] on api.nan.builders is deployed and verified.

[sre-helmcode]

Workspaces aligned with cloud-api #324/#325 and nan-devops #805. QA (Opus, foreground, checked against cloud-api origin/main b9fb33b and live api.nan.builders with fake credentials) APPROVED at head 9c2cce1.