API Endpoints

Every endpoint requires the x-api-key: <api_key> header unless noted. JSON request and response bodies. Errors follow the shape in REST API → Errors.

Agents

GET /v1/agents

List all agents in the tenant. Query params: archived (bool), limit, cursor.

POST /v1/agents

Create an agent. Body: AgentConfig minus the platform-assigned fields (id, version, timestamps).

GET /v1/agents/:id

Get a single agent’s current version.

GET /v1/agents/:id/versions

List all versions of an agent.

GET /v1/agents/:id/versions/:version

Get a specific historical version.

PATCH /v1/agents/:id

Update an agent. Bumps version. Body: partial AgentConfig.

DELETE /v1/agents/:id

Archive an agent (soft delete; sessions retain pinned version).

Sessions

POST /v1/sessions

Create a session. Returns SessionMeta.

{
  "agent": "agent_...",
  "environment_id": "env_...",
  "title": "optional"
}

Post the first user turn afterwards via POST /v1/sessions/:id/messages (one-shot, streams reply) or POST /v1/sessions/:id/events (fire-and-forget; pair with a separate SSE consumer).

GET /v1/sessions

List sessions. Query: agent_id, status, limit, cursor.

GET /v1/sessions/:id

Get session metadata + status.

GET /v1/sessions/:id/events

JSON-paginated event log. Query: limit (1–1000, default 100), order (asc|desc), after_seq. Returns { data: SessionEvent[], has_more, next_page }.

Pass Accept: text/event-stream to switch to the SSE variant (or call /v1/sessions/:id/events/stream directly). Default behavior is Anthropic-spec-aligned: no history replay, only the spec event union (third-party @anthropic-ai/sdk parses cleanly). Two opt-ins:

• ?include=chunks — admit OMA extension events (token chunks, lifecycle, system.user_message_*, session.warning, extra spans like aux.model_call)
• ?replay=1 (or Last-Event-ID: <seq> header) — replay persisted history before tailing

See REST API → Stream session events for the full event tables.

GET /v1/sessions/:id/log

Full event log as a JSON array (non-streaming).

POST /v1/sessions/:id/messages

Chatbot one-shot: post a user turn AND stream the response in one HTTP call. Body: { "content": string | ContentBlock[] }. Returns text/event-stream and auto-closes when the turn finishes (session.status_idle). For the fire-and-forget variant (when you already have a separate SSE consumer open), POST to /v1/sessions/:id/events instead with the user.message wrapped in {events:[...]} — returns 202.

POST /v1/sessions/:id/cancel

Cancel a running session.

DELETE /v1/sessions/:id

Soft-delete a session.

Environments

GET /v1/environments

List environment templates.

POST /v1/environments

Create an environment. Body: EnvironmentConfig.

GET /v1/environments/:id

Get one.

PATCH /v1/environments/:id

Update.

DELETE /v1/environments/:id

Delete (only if no agents reference it).

Skills

GET /v1/skills

List custom + built-in skills.

POST /v1/skills

Upload a custom skill. multipart/form-data with id, display_title, description, and one or more files.

GET /v1/skills/:id

Get metadata.

GET /v1/skills/:id/files/:filename

Download a skill file.

DELETE /v1/skills/:id

Delete (built-in skills can’t be deleted).

Vaults

GET /v1/vaults

List. Returned objects never include the secret material.

POST /v1/vaults

Create. Body includes the secret; subsequent reads will not.

PATCH /v1/vaults/:id

Update — including rotating the secret.

DELETE /v1/vaults/:id

Delete.

Memory Stores

GET /v1/memory_stores

List per agent.

POST /v1/memory_stores

Create.

GET /v1/memory_stores/:id/entries

List recent entries.

POST /v1/memory_stores/:id/search

Semantic search. Body: { "query": "...", "limit": 10 }.

DELETE /v1/memory_stores/:id

Delete the store and its index.

Files

POST /v1/files

Upload. multipart/form-data with session_id and file.

GET /v1/files/:id

Download.

DELETE /v1/files/:id

Delete.

Model Cards

Per-tenant LLM credentials. Keys are AES-256-GCM-encrypted at rest under PLATFORM_ROOT_SECRET directly on the row (no Vault indirection). List responses surface only the last-4 preview.

GET /v1/model_cards

List configured model cards.

POST /v1/model_cards

Add a model card. Runs a 6-second capability probe so a bad key fails loudly. Body:

{
  "model_id": "my-anthropic",
  "provider": "ant",
  "model": "claude-sonnet-4-6",
  "base_url": "https://api.anthropic.com",
  "custom_headers": { "x-extra": "..." },
  "api_key": "sk-ant-..."
}

provider is one of ant | ant-compatible | oai | oai-compatible. model_id is the string an agent sets as agent.model = "<model_id>" to bind this card.

POST /v1/model_cards/:id

Rotate the api_key, base_url, headers, or default model. Body shape matches POST. In-flight sessions keep the cached key until next credential resolve.

DELETE /v1/model_cards/:id

Delete.

GET /v1/model_cards/:id/key (internal — agent worker only)

Returns cleartext credentials for the agent worker. Not exposed publicly.

Integrations

GET /v1/integrations

List shipped + active integrations.

GET /v1/integrations/:id/install

Start the OAuth flow for the integration. Returns a redirect URL.

POST /v1/integrations/:id/uninstall

Revoke the install.

GET /v1/integrations/:id/publications

List publications (which agents serve which workspaces).

POST /v1/integrations/:id/publications

Create a publication.

DELETE /v1/integrations/:id/publications/:pub_id

Delete a publication.

Evals

GET /v1/evals

List eval runs.

POST /v1/evals

Start an eval.

GET /v1/evals/:id

Get an eval’s results.

API Keys

GET /v1/api_keys

List your keys (the actual key value is not returned).

POST /v1/api_keys

Create. Body: { "name": "..." }. Returns the key once — store it now.

DELETE /v1/api_keys/:id

Revoke.

OAuth (Console use)

GET /v1/oauth/:provider/authorize

Start an OAuth flow (Google sign-in for the Console).

GET /v1/oauth/:provider/callback

OAuth callback handler.

Health

GET /healthz

Returns {"ok": true}. Unauthenticated.

Where to go next

REST API overview Patterns, auth, error handling.

CLI & SDK Skip curl: use the Node CLI.

Configuration reference Body schemas for all the request payloads above.