Core API Reference

This is the consolidated reference for the core platform API — the one page to reach for when you need to know which API does what, how responses are shaped, and where a given endpoint lives. When in doubt, start here. For exhaustive per-endpoint request/response field detail, this reference points you to the authoritative core API contract; for your plugin's own endpoints, see The Plugin API Surface.

The four surfaces

The core API is really four surfaces, distinguished by audience and auth:

#	Surface	Audience	Auth
1	Core API	the UI	Operator JWT
2	Workflow execution API (UI-facing)	the UI	Operator JWT
3	Machine API (/api/machine/*)	the workflow engine	API Key
4	Plugin-owned API	per plugin	Operator JWT

Surfaces 1–3 are the core-owned ones covered here; surface 4 is documented per plugin. (For the design rationale, see the Architect Four API Surfaces.)

The response envelope

Every response uses the standard envelope:

// success (single)
{ "data": { ... } }

// success (list)
{ "data": [ ... ], "meta": { "total": 42, "page": 1, "per_page": 25 } }

// error
{ "error": { "status": 400, "code": "VALIDATION_ERROR", "message": "…", "details": [ … ] } }

Standard error codes

HTTP	Code	When
400	VALIDATION_ERROR	generic field validation failure
401	UNAUTHORIZED / TOKEN_EXPIRED / TOKEN_REVOKED	missing / invalid / expired / revoked credentials
403	FORBIDDEN / CSRF_FAILURE	valid auth but wrong route class / missing CSRF
404	NOT_FOUND	resource does not exist
409	CONFLICT	business-rule violation; EXTERNAL_EXECUTION_ID_CONFLICT on machine callbacks
429	RATE_LIMITED	too many requests
500	INTERNAL_ERROR	unexpected server error

Feature-specific codes follow DOMAIN_SPECIFIC_REASON in uppercase; plugin codes are prefixed with the plugin slug.

Surface 1 — Core API (Operator JWT)

Auth (/auth): GET /auth/status, POST /auth/register, POST /auth/confirm, POST /auth/login, POST /auth/login/2fa, POST /auth/password/forgot (public); GET /auth/me, POST /auth/logout, POST /auth/password/change, POST /auth/2fa/setup, POST /auth/2fa/verify, POST /auth/2fa/disable, plus API-key management under /auth/api-keys (browser-authenticated).

Configuration registries (/api/...): CRUD for the platform's registries — models, agents, prompts (families / prompts / versions), services, workflow configs, service configs, workflows, workflow engines, system context, and system-wide configuration. These follow standard REST shapes and the envelope above.

Dashboard & analytics (/api/...): the dashboard aggregates and the cost/analytics queries.

Surface 2 — Workflow execution API (UI-facing, Operator JWT)

Used by the UI (and plugin UI) to run and inspect executions:

• POST /api/workflow-executions/start — start a run ({ workspace_id, workflow_id, is_test? }).
• POST /api/workflow-executions/:id/retry — retry a failed_transient execution.
• POST /api/workflow-executions/:id/terminate — operator termination of a running execution.
• POST /api/workflow-executions/:id/terminate-queued — operator termination of a queued execution.
• GET /api/workflow-executions?workspaceId=... — history for a workspace.
• GET /api/workflow-executions/:id — execution detail with snapshots and logs.
• GET /api/workspaces/:workspaceId/available-workflows — the workflows eligible for a workspace (drives the picker).

Surface 3 — Machine API (/api/machine/*, API Key)

The endpoints the workflow engine's Circus nodes call:

• POST /api/machine/health — health / credential check.
• POST /api/machine/workflow-executions/:id/logs — append a log entry; the response carries the cost/time tally and abort flag.
• POST /api/machine/workflow-executions/:id/complete — mark success and submit the result payload.
• POST /api/machine/workflow-executions/:id/terminate — mark failure.

All machine callbacks require the external_execution_id; a mismatch is rejected with 409. (These are covered from the workflow's side in the Workflow Developer package.)

When you need exact fields

This page is the map; the authoritative core API contract (009_core_api_contract_v1.md) holds the exact request/response fields, validation rules, and per-endpoint error codes for surfaces 1–3, and the workflow execution lifecycle covers the execution endpoints in depth. For a plugin's own surface, its plugin API contract is authoritative. Cite an endpoint's purpose and the authoritative doc rather than hardcoding assumptions — names can change; the surfaces and their roles don't.