REST API - Meerkat

Meerkat ships a REST server for running and managing agent sessions over HTTP. This is the best fit if you want a simple, language-agnostic API for the Meerkat core.

Getting started

Configure provider credentials

For the simplest environment-backed setup, export the key for your chosen provider before launching the server. Realm auth profiles and bindings are the persistent alternative:

export ANTHROPIC_API_KEY="sk-..."

Start the server

In that same configured terminal, start the installed binary:

rkat-rest --realm team-alpha

Send a request

Leave the server running and use another terminal for curl. Select an Anthropic model to match the key above:

curl -X POST http://127.0.0.1:8080/sessions \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello, Meerkat!", "model": "claude-opus-5", "provider": "anthropic"}'

Runtime scope

rkat-rest accepts:

--realm <id>
--isolated
--instance <id>
--realm-backend <sqlite|jsonl|memory>
--state-root <path>
--context-root <path>
--user-config-root <path>
--expose-paths

If --realm is omitted, the server creates a new isolated opaque realm (realm-...). --realm-backend is a creation hint only; after first open, realm_manifest.json is authoritative.

The REST server has no general inbound HTTP authentication layer. The auth/* routes manage outbound provider credentials; they do not authenticate callers to this API. Keep the listener on loopback or put it behind an authenticated, encrypted reverse proxy. The optional webhook-secret check protects only POST /sessions/{id}/external-events and POST /sessions/{id}/peer-response-terminal, not the other routes.

Endpoint overview

This overview follows the generated OpenAPI artifact at artifacts/schemas/rest-openapi.json.

Method	Path	Description
`POST`	`/help`	Ask Meerkat usage help with the embedded platform skill
`POST`	`/sessions`	Create and run a new session
`GET`	`/sessions`	List sessions
`GET`	`/sessions/{id}`	Fetch session metadata and usage
`GET`	`/sessions/{id}/status`	Fetch current runtime state for a session
`GET`	`/sessions/{id}/history`	Fetch committed session transcript messages
`POST`	`/sessions/{id}/system_context`	Append one ordinary durable ordered System message
`POST`	`/sessions/{id}/system_prompt`	Replace one durable versioned system-prompt key
`POST`	`/sessions/{id}/messages`	Continue an existing session
`POST`	`/sessions/{id}/external-events`	Queue a runtime-backed external event
`POST`	`/sessions/{id}/peer-response-terminal`	Queue a typed peer terminal response event
`POST`	`/sessions/{id}/interrupt`	Interrupt an in-flight turn
`DELETE`	`/sessions/{id}`	Archive (remove) a session
`GET`	`/sessions/{id}/events`	SSE stream for real-time updates
`GET`	`/schedule/tools`	List schedule tool definitions
`POST`	`/schedule/call`	Call a schedule tool directly
`POST`	`/schedules`	Create a schedule
`GET`	`/schedules`	List schedules
`GET`	`/schedules/{id}`	Fetch one schedule
`PATCH`	`/schedules/{id}`	Update a schedule
`DELETE`	`/schedules/{id}`	Delete a schedule
`POST`	`/schedules/{id}/pause`	Pause a schedule
`POST`	`/schedules/{id}/resume`	Resume a schedule
`GET`	`/schedules/{id}/occurrences`	List schedule occurrences
`GET`	`/workgraph/items`	List WorkGraph items
`GET`	`/workgraph/items/{id}`	Fetch one WorkGraph item
`GET`	`/workgraph/ready`	List ready WorkGraph items
`GET`	`/workgraph/snapshot`	Read a WorkGraph observability snapshot
`GET`	`/workgraph/events`	Read WorkGraph event history
`POST`	`/workgraph/goal/status`	Read goal and attention status
`POST`	`/workgraph/attention/list`	List attention bindings
`POST`	`/sessions/{id}/mcp/add`	Stage live MCP server addition (mcp feature)
`POST`	`/sessions/{id}/mcp/remove`	Stage live MCP server removal (mcp feature)
`POST`	`/sessions/{id}/mcp/reload`	Reload MCP server(s) (mcp feature)
`POST`	`/comms/send`	Push comms message into a session (comms feature)
`GET`	`/comms/peers`	List discoverable peers (comms feature)
`GET`	`/auth/profiles`	List realm auth profiles, backend profiles, and bindings
`POST`	`/auth/profiles`	Store binding-scoped credentials
`GET`	`/auth/bindings/{binding_id}`	Read a binding-scoped auth profile
`DELETE`	`/auth/bindings/{binding_id}`	Delete binding-scoped credentials
`POST`	`/auth/bindings/{binding_id}/test`	Test a binding resolve path
`POST`	`/auth/login/start`	Start interactive auth login
`POST`	`/auth/login/complete`	Complete interactive auth login
`POST`	`/auth/login/device/start`	Start device-code login
`POST`	`/auth/login/device/complete`	Complete device-code login
`GET`	`/auth/bindings/{binding_id}/status`	Read binding auth status
`POST`	`/auth/bindings/{binding_id}/logout`	Log out a binding
`GET`	`/realms`	List configured realms
`GET`	`/realms/{id}`	Read one realm
`GET`	`/mob/{id}/events`	Mob event SSE stream (mob feature)
`POST`	`/mob/{id}/spawn-helper`	Spawn a helper into a mob (mob feature)
`POST`	`/mob/{id}/fork-helper`	Fork a helper from an existing member (mob feature)
`POST`	`/mob/{id}/wait-kickoff`	Wait for kickoff completion (mob feature)
`POST`	`/mob/{id}/wire-members-batch`	Wire multiple mob members in one request (mob feature)
`GET`	`/mob/{id}/members/{agent_identity}/status`	Read member status (mob feature)
`GET`	`/mob/{id}/members/{agent_identity}/tool-declaration`	Read durable tool declaration and convergence status as `MobMemberToolDeclarationResult` (mob feature)
`PUT`	`/mob/{id}/members/{agent_identity}/tool-declaration`	Apply a declaration with exact-revision CAS: `RestApplyMemberToolDeclarationRequest` → `MobApplyMemberToolDeclarationResult` (mob feature)
`POST`	`/mob/{id}/members/{agent_identity}/identity-adoption`	Adopt an existing member under an expected-absent precondition: `RestAdoptMemberIdentityDeclarationRequest` → `MobAdoptMemberIdentityDeclarationResult` (mob feature)
`POST`	`/mob/{id}/members/{agent_identity}/tool-convergence/resolve`	Resolve blocked identity convergence against desired/active revisions: `RestResolveIdentityConvergenceBlockRequest` → `MobResolveIdentityConvergenceBlockResult` (mob feature)
`POST`	`/mob/{id}/members/{agent_identity}/cancel`	Force-cancel a member (mob feature)
`POST`	`/mob/{id}/members/{agent_identity}/respawn`	Respawn a member (mob feature)
`GET`	`/mob/{id}/members/{agent_identity}/history`	Read a mob member transcript page by identity (mob feature)
`GET`	`/mob/{id}/hosts`	List tracked member hosts with bind phase and capabilities (mob feature)
`GET`	`/mob/{id}/route-installs`	Outstanding cross-host route-install obligations (mob feature)
`GET`	`/skills`	List skills with provenance
`GET`	`/health`	Liveness check
`GET`	`/runtime/host_info`	Read runtime host identity, endpoints, and realm projection
`GET`	`/runtime/capabilities`	Read runtime host capability flags
`GET`	`/runtime/health`	Read runtime host health
`GET`	`/models/catalog`	Curated model catalog with provider profiles
`GET`	`/capabilities`	Runtime capabilities
`GET`	`/config`	Read config
`PUT`	`/config`	Replace config
`PATCH`	`/config`	Merge-patch config (RFC 7396)
`POST`	`/requests/{request_id}/cancel`	Cancel an uncommitted in-flight request

Helper requests (/mob/{id}/spawn-helper, /mob/{id}/fork-helper) require result_label and max_text_bytes. Spawn and fork responses are exact-operation results with required output, tokens_used, agent_identity, member_ref, bounded_result, session_id, usage, turns, and tool_calls; retirement_error is present only when cleanup debt remains after the certified result was captured.

Schedule endpoints return the same flattened public Schedule contract as JSON-RPC. Planning, labels, and created/updated timestamps are top-level; there is no nested config and persisted machine_state is not public.

WorkGraph goal and attention mutation routes require trusted in-process host/session authority and are not part of the public REST catalog. Approvals, durable jobs and monitors, stable artifact record/download methods, and low-latency live channels are not REST routes. Those operator surfaces are available through JSON-RPC and the generated SDKs. REST history can carry blob references, but REST does not expose blob or artifact download paths. Multi-host mob administration (host bind/revoke, hard-cancel, member live channels, grant management) is deliberately NOT served by REST — REST carries observation GETs only. The complete admin family lives on JSON-RPC and the Python/TypeScript SDKs; host binding/revoke, grants, and live control also have CLI verbs, while hard cancel is RPC/SDK-only. Durable member role migration is also outside the public REST contract. The shared OpenAPI component catalog includes private member-host bridge schemas, including MaterializeLaunchMode, because components are generated from shared wire types. No REST path accepts resume_from_role; only a trusted Rust host or the private member-host materialization protocol can issue that one-shot declaration. The paths object, not component reachability, defines REST exposure.

Generated images are not returned as inline bytes in history. GET /sessions/{id}/history returns assistant image blocks with image_id, blob_ref, dimensions, and metadata; fetch image bytes through the blob/artifact surface exposed by the runtime-backed RPC/SDK path.

REST keeps observation and helper endpoints for mobs, but typed lifecycle/control for app hosts lives on the canonical RPC/SDK mob/* surface. Inside running sessions, mob capability is still exposed by composing meerkat-mob-mcp (MobMcpState + AgentMobToolSurfaceFactory) into SessionBuildOptions.mob_tools in the host runtime. external_tools remains reserved for callback and MCP-backed dispatchers.

WorkGraph REST endpoints are observability/operator lookup, including goal-status and attention-list reads. Agents create, claim, update, link, evidence, close, reassign attention, and escalate policy through WorkGraph tools inside sessions; goal and attention mutators stay on trusted in-process host authority.

Request cancellation

REST request cancellation is opt-in and request-ID based.

send X-Meerkat-Request-Id: <id> on POST /sessions or POST /sessions/{id}/messages
call POST /requests/{request_id}/cancel to cancel uncommitted in-flight work
duplicate in-flight request IDs are rejected

Cancellation only affects uncommitted work:

pre-start / pre-commit work may return cancelled
committed success is not rewritten to cancellation
post-commit create failures still return session identity and remain resumable

Configuration

Server configuration details

REST configuration is realm-scoped:

macOS: ~/Library/Application Support/meerkat/realms/<realm>/config.toml
Linux: ~/.local/share/meerkat/realms/<realm>/config.toml
Windows: %APPDATA%\\meerkat\\realms\\<realm>\\config.toml

Each realm also has realm_manifest.json (backend pinning) and config_state.json (generation CAS state).Key sections:

[rest]
host = "127.0.0.1"
port = 8080

[agent]
model = "claude-opus-4-8"
max_tokens_per_turn = 8192

[tools]
builtins_enabled = false
shell_enabled = false
schedule_enabled = true
workgraph_enabled = false

API keys are provided via environment variables:

ANTHROPIC_API_KEY
OPENAI_API_KEY
GOOGLE_API_KEY

Endpoints

POST /help

Ask Meerkat usage help with the embedded platform skill.

Request

{
  "question": "How do I add an MCP server?"
}

Returns a HelpResponse with the answer text and any plan metadata requested by the input.

POST /sessions

Create and run a new session.

{
  "prompt": "Your prompt here"
}

{
  "prompt": "Your prompt here",
  "system_prompt": "Optional system prompt",
  "model": "claude-opus-4-8",
  "provider": "anthropic",
  "max_tokens": 4096,
  "output_schema": {
    "schema": {"type": "object", "properties": {"answer": {"type": "string"}}},
    "name": "answer",
    "strict": false,
    "compat": "lossy",
    "format": "meerkat_v1"
  },
  "structured_output_retries": 2,
  "verbose": false,
  "keep_alive": null,
  "comms_name": null,
  "peer_meta": null,
  "hooks_override": null,
  "enable_builtins": null,
  "enable_shell": null,
  "enable_memory": null,
  "enable_schedule": null,
  "enable_workgraph": null
}

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "text": "Response text",
  "turns": 1,
  "tool_calls": 0,
  "usage": {
    "input_tokens": 50,
    "output_tokens": 200,
    "total_tokens": 250
  }
}

Request fields

ContentInput (string | ContentBlock[])

required

The user prompt: a string or a typed content-block array, for example [{"type":"text","text":"Hello"}]. Media blocks depend on the selected model/provider; see model capabilities.

ContentInput[] | null

default:"null"

Host-attached injected context for the first turn. Each entry materializes as a separate typed injected-context user-channel message immediately before the first turn’s user message, in order; injected context is excluded from semantic-memory indexing. Older REST servers silently ignore this field (existing REST version-skew posture).

string | null

default:"null"

Non-empty, exact host-regenerated facts for the first logical turn. Whitespace is significant. Meerkat persists the text only with the pending runtime input for crash retry and projects it as a request-local user-channel context message immediately before that turn’s conversational user message. It never enters Session history, compaction, or extraction requests.

SystemPromptOverride

default:"inherit"

Typed per-request system-prompt policy: omit/null to inherit, a string to set an explicit prompt, or {"action": "disable"} to suppress every prompt source.

string | null

default:"config default"

Model name (e.g. "claude-opus-4-8", "gpt-5.5").

string | null

default:"inferred from model"

Provider: "anthropic", "openai", "gemini", "self_hosted", "other".

WireAuthBindingRef | null

default:"null"

Optional structural credential selector, for example {"realm":"prod","binding":"anthropic","profile":"claude_oauth"}. realm and binding are required when supplied; profile is optional. Configure the referenced realm, binding, and auth profile first. Omission/null lets the create resolver select credentials. This is an object, not the CLI’s colon-delimited string; provenance is server-owned.

u32 | null

default:"config default"

Max tokens per turn.

OutputSchema | null

default:"null"

JSON schema for structured output extraction (wrapper or raw schema).

u32 | null

default:"null"

Max retries for structured output validation. null/omitted uses the server default on create and inherits the persisted session value on continue.

bool

default:"false"

Enable verbose event logging (server-side).

bool | null

default:"null"

Keep session alive after turn for comms. On create, null/omitted uses the create default (false), true enables, and false explicitly disables. Requires comms_name when enabled.

string | null

default:"null"

Agent name for inter-agent communication.

object | null

default:"null"

Friendly metadata for peer discovery (name, description, labels).

HookRunOverrides | null

default:"null"

Run-scoped hook overrides (see Hooks).

bool | null

default:"null (factory default)"

Enable built-in tools (task management, etc.). Omit to use factory defaults.

bool | null

default:"null (factory default)"

Enable shell tool (requires enable_builtins). Omit to use factory defaults.

bool | null

default:"null (factory default)"

Enable semantic memory. Omit to use factory defaults.

bool | null

default:"null (factory default)"

Override schedule tools for this session. Omit to use factory defaults.

bool | null

default:"null (factory default)"

Override WorkGraph tools for this session. Omit to use factory defaults.

Response fields

string

UUID of the created session.

string

The agent’s response text.

u32

Number of LLM calls made.

u32

Number of tool calls executed.

WireUsage

Token usage breakdown.

JSON (optional)

Parsed structured output when extraction succeeds. Omitted when absent.

ExtractionError (optional)

Post-turn extraction failure details: last_output is the committed main-turn assistant text that extraction attempted to transform, attempts is the number of extraction attempts made, and reason describes the failure. Omitted when absent.

SchemaWarning[] (optional)

Schema compatibility warnings per provider. Omitted when absent.

A successful response can contain committed text even if post-turn structured-output extraction fails. Inspect both structured_output and extraction_error; missing structured output does not prove extraction was never requested. These optional REST fields are omitted when absent, not filled with null.

GET /sessions//history

Read committed transcript history for a session without changing the lightweight metadata shape of GET /sessions/{id}. Query parameters:

offset — skip this many messages from the start of the transcript
limit — cap the number of returned messages

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "message_count": 8,
  "offset": 0,
  "limit": 50,
  "has_more": false,
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello" },
    {
      "role": "block_assistant",
      "blocks": [{ "block_type": "text", "data": { "text": "Hi there." } }],
      "stop_reason": "end_turn"
    }
  ]
}

History is returned oldest-to-newest and reflects the last committed session snapshot only.

POST /sessions/{id}/system_context

Append one ordinary durable ordered System message at the admitted transcript boundary. content uses the CoreRenderable tagged shape, and the optional idempotency_key makes an exact caller retry safe.

Request

{
  "content": {"type": "text", "text": "Treat the incident as severity one."},
  "source": "incident-controller",
  "idempotency_key": "incident-42-policy-v1"
}

Response

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "status": "applied"
}

POST /sessions/{id}/system_prompt

Replace one keyed system-prompt slot with version CAS. The first explicit adoption supplies target_message_index for an existing unversioned System row and omits expected_version. Later updates omit the target and provide the latest expected_version. expected_parent_revision optionally adds a transcript-head CAS.

Request

{
  "key": "operator-policy",
  "expected_version": 1,
  "content": "Escalate critical actions for human approval.",
  "actor": "operator:alice"
}

The result contains session_id, key, the new version, message_index, status (applied or duplicate), transcript_revision, and an optional rewrite commit. Mob-owned system prompts must be updated through their mob owner and are rejected on this session route.

GET /sessions

List sessions. Supports optional label filters via query parameters.

Response

{
  "sessions": [
    {
      "session_id": "01936f8a-7b2c-7000-8000-000000000001",
      "created_at": 1736937000,
      "updated_at": 1736937060,
      "message_count": 4,
      "total_tokens": 500,
      "is_active": false
    }
  ]
}

Each row is a WireSessionSummary. created_at and updated_at are Unix seconds. is_active is the reported session activity flag, not a full runtime-state enum; use the status endpoint for runtime state. Optional session_ref and non-empty labels may also be present. The separate GET /sessions/{id} detail response retains its RFC3339 timestamp strings.

POST /sessions/{id}/messages

Continue an existing session.

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "prompt": "Follow-up message"
}

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "text": "Response to follow-up",
  "turns": 1,
  "tool_calls": 0,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 150,
    "total_tokens": 250
  }
}

Request fields

string

required

Session ID (must match the path {id}).

ContentInput (string | ContentBlock[])

required

Follow-up prompt as text or typed content blocks, for example [{"type":"text","text":"Continue"}]. Media support is model/provider dependent; see model capabilities.

ContentInput[] | null

default:"null"

Host-attached injected context for this turn. Each entry materializes as a separate typed injected-context user-channel message immediately before the turn’s user message, in order; injected context is excluded from semantic-memory indexing. Older REST servers silently ignore this field (existing REST version-skew posture).

string | null

default:"null"

Non-empty, exact host-regenerated facts for this logical turn. Whitespace is significant. The value is available to every foreground provider call and retry in the turn, persists only while the runtime input is pending, and never becomes a Session message.

string | null

default:"null"

Override the system prompt.

string | null

default:"from session"

Model override for this turn. On materialized sessions this hot-swaps the LLM client for the remainder of the session.

string | null

default:"from session"

Provider override for this turn. Typically inferred from model. Used with model for mid-session provider switching.

u32 | null

default:"from session"

Max tokens override for this turn.

OutputSchema | null

default:"null"

Structured output schema for this turn.

u32 | null

default:"null"

Max retries for structured output validation. Omit / null to inherit the persisted session value on continue.

bool

default:"false"

Enable verbose event logging.

bool | null

default:"null"

Keep-alive override for this turn. null = inherit persisted session intent, true = enable, false = disable.

string | null

default:"from session"

Agent name for comms.

HookRunOverrides | null

default:"null"

Run-scoped hook overrides.

Response fields

Same shape as POST /sessions.

POST /sessions/{id}/interrupt

Interrupt an in-flight turn. No-op if the session is idle.

Response

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "interrupted": true,
  "result": "interrupted"
}

interrupted is derived from the typed result. The public classifier also reports "interrupted"/true for an existing idle session’s no-op; it is not proof that a live turn was cancelled. The shared result type also has "staged_noop"/false for staged sessions on RPC’s deferred-create path; REST does not expose deferred creation. Typed failures remain HTTP errors, not successful interrupt results.

POST /requests/{request_id}/cancel

Cancel an uncommitted in-flight request that previously supplied X-Meerkat-Request-Id.

Response

{"cancelled": true}

Returns 200 with {"cancelled": false, "reason": "already_terminal"} when the tracked request already published or completed. Returns 404 only when the request ID is unknown.

DELETE /sessions/{id}

Archive (remove) a session.

Response

{"archived": true}

Returns 404 if the session is not found.

POST /sessions/{id}/external-events

Queue an external event through the runtime-backed admission path.

curl -X POST http://localhost:8080/sessions/01936f8a-7b2c-7000-8000-000000000001/external-events \
  -H "Content-Type: application/json" \
  -d '{"kind": "generic_json", "event_type": "monitor.alert", "payload": {"alert": "CPU spike", "host": "web-03"}}'

curl -X POST http://localhost:8080/sessions/01936f8a-7b2c-7000-8000-000000000001/external-events \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: my-secret" \
  -d '{"kind": "generic_json", "event_type": "deployment.alert", "payload": {"alert": "deployment failed"}}'

{"queued": true}

When RKAT_WEBHOOK_SECRET is configured on the server, this route requires the X-Webhook-Secret header. Admission queues the event without waking an idle session. Correlated terminal peer responses use POST /sessions/{id}/peer-response-terminal, not this generic event route.

string

required

Must be "generic_json". The "peer_response_terminal" tag is reserved and rejected here.

string

required

Event classification, for example "monitor.alert".

JSON

required

Application payload inside the tagged envelope, not a flat request body.

WireContentBlock[] | null

default:"null"

Optional typed content blocks accompanying the event.

string

Webhook secret for authentication. Required when RKAT_WEBHOOK_SECRET env var is set on the server. Compared using constant-time equality (subtle::ConstantTimeEq).

HTTP Status	When
202	Event queued successfully
404	Session not found
401	Missing or invalid webhook secret
503	Event inbox is full

POST /sessions/{id}/peer-response-terminal

Admit a terminal peer response through the typed runtime ingress. Like external-events, this route requires X-Webhook-Secret when the server has RKAT_WEBHOOK_SECRET configured; a missing or invalid secret returns HTTP 401. The following example assumes that secret is enabled:

With webhook secret

curl -X POST http://localhost:8080/sessions/01936f8a-7b2c-7000-8000-000000000001/peer-response-terminal \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: my-secret" \
  -d '{
    "peer_id": "00000000-0000-4000-8000-000000000161",
    "display_name": "analyst",
    "request_id": "00000000-0000-4000-8000-000000000162",
    "status": "completed",
    "result": {"token": "silver harbor"}
  }'

string

Required when RKAT_WEBHOOK_SECRET is set on the server; omit only when webhook-secret authentication is disabled.

string

required

Canonical peer routing ID. Display names are not accepted as routing identity.

string

Optional presentation label.

string

required

Peer correlation ID for the request this terminal response completes.

string

required

Terminal response status: "completed", "failed", or "cancelled".

any JSON

required

Peer-returned terminal payload.

GET /sessions/{id}

Fetch session metadata and usage.

Response

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:00Z",
  "message_count": 4,
  "total_tokens": 500
}

GET /sessions/{id}/events

Server-Sent Events (SSE) stream for real-time updates. Event types:

Event	Description
`session_loaded`	Emitted on connect with session metadata
`run_started`	Agent execution began
`run_completed`	Agent run finished
`run_failed`	Agent run failed
`turn_started`	New LLM call within the turn
`text_delta`	Streaming text chunk from LLM
`text_complete`	Full text for this turn
`tool_call_requested`	LLM wants to call a tool
`tool_result_received`	Tool result processed
`turn_completed`	LLM call finished
`tool_execution_started`	Tool dispatch began
`tool_execution_completed`	Tool returned a result
`tool_execution_timed_out`	Tool exceeded timeout
`compaction_started`	Context compaction began
`compaction_completed`	Compaction finished
`compaction_failed`	Compaction failed
`budget_warning`	Approaching resource limits
`retrying`	Retrying after transient error
`hook_started`	Hook execution began
`hook_completed`	Hook finished
`hook_failed`	Hook execution failed
`hook_denied`	Hook blocked operation
`skills_resolved`	Skills loaded for turn
`skill_resolution_failed`	Skill resolution failed
`stream_truncated`	An upstream bounded subscriber reported lag and a dropped count; not guaranteed for REST transport loss
`done`	Emitted when the broadcast channel closes

The live SSE subscription is bounded and best-effort. Upstream stream_truncated envelopes can be forwarded, but the REST transport’s own broadcast receiver can also lose events without a marker or dropped count. Do not infer completeness from the absence of a lag marker. Built-in realm-backed persistent sessions can feed an optional durable audit projector through a separate unbounded queue, so SSE lag does not drop its input. That audit log is asynchronous derived state, not a guaranteed complete replay. Reconnect and reconcile from session history/status, or use the JSON-RPC events/* methods when that optional replay surface is installed and healthy.

GET /skills

List all skills with provenance information. Returns active and shadowed entries.

Response

{
  "skills": [
    {
      "key": {
        "source_uuid": "00000000-0000-4b11-8111-000000000001",
        "skill_name": "task-workflow"
      },
      "name": "Task Workflow",
      "description": "How to use task tools",
      "scope": "builtin",
      "source": {
        "source_uuid": "00000000-0000-4b11-8111-000000000001",
        "display_name": "embedded",
        "transport_kind": "embedded",
        "fingerprint": "embedded:inventory",
        "status": "active"
      },
      "is_active": true
    },
    {
      "key": {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "skill_name": "task-workflow"
      },
      "name": "Custom Task Workflow",
      "description": "Override tasks",
      "scope": "project",
      "source": {
        "source_uuid": "dc256086-0d2f-4f61-a307-320d4148107f",
        "display_name": "company",
        "transport_kind": "git",
        "fingerprint": "repo-7cc66f36fd9db1a1",
        "status": "active"
      },
      "is_active": true
    }
  ]
}

Returns 404 if skills are not enabled.

GET /health

Returns "ok" (HTTP 200). Use for liveness checks.

GET /runtime/host_info

Returns the read-only RuntimeHostInfo projection: process identity, host ID scope, realm and endpoint metadata, feature flags, and the same health payload as GET /runtime/health. It does not enroll a host or grant placement authority.

GET /runtime/capabilities

Returns RuntimeHostCapabilities, a contract version plus boolean RuntimeHostFeatureFlags. These host feature flags are distinct from the generic status entries returned by GET /capabilities.

GET /runtime/health

Returns RuntimeHostHealth with status and a checks map. The declared dimensions are jobs, session_liveness, session_durability, session_runtime_loop, and session_run_start. REST measures the four session dimensions. It has no detached-job service probe, so it reports unmeasured:jobs as a coverage marker and leaves that marker out of the status rollup. A plain dimension key is a measured result. unreadable:<dimension> means the probe ran but could not obtain a reading and rolls the overall status up to at least degraded. unmeasured:<dimension> means this surface has no probe and does not by itself make a healthy host permanently degraded.

GET /models/catalog

Return the curated model catalog with provider profiles, capability metadata, and parameter schemas.

Response (abbreviated)

{
  "contract_version": {"major": 0, "minor": 8, "patch": 42},
  "providers": [
    {
      "provider": "anthropic",
      "default_model_id": "claude-opus-5-5",
      "models": [
        {
          "id": "claude-opus-5",
          "display_name": "Claude Opus 5",
          "tier": "recommended",
          "context_window": 1000000,
          "max_output_tokens": 128000,
          "profile": {
            "model_family": "claude-opus-5",
            "supports_temperature": false,
            "supports_thinking": true,
            "supports_reasoning": false,
            "params_schema": {}
          }
        }
      ]
    }
  ]
}

The catalog is resolved from built-in model metadata plus config-backed provider/server entries. Each provider entry includes the default model and a list of models with their capabilities and parameter schemas.

GET /capabilities

Returns runtime capabilities with status resolved against config.

Response (abbreviated)

{
  "contract_version": {"major": 0, "minor": 8, "patch": 42},
  "capabilities": [
    {
      "id": "sessions",
      "description": "Session lifecycle management",
      "status": "Available"
    },
    {
      "id": "shell",
      "description": "Shell command execution",
      "status": {"DisabledByPolicy": {"description": "Disabled by config"}}
    }
  ]
}

The full response includes all registered capabilities from the running build, including sessions, streaming, structured_output, hooks, builtins, shell, comms, memory_store, schedule, work_graph, session_store, session_compaction, skills, and mcp_live when their owning crates are linked. See the JSON-RPC API for the corresponding RPC surface.

GET /config

Returns a realm config envelope:

config
generation
realm_id
instance_id
backend
resolved_paths

PUT /config

Replaces config. Accepted request forms:

Direct config object (compat)
Wrapped form with CAS:
- { "config": <Config>, "expected_generation": <u64|null> }

PATCH /config

Applies RFC 7396 merge patch. Accepted request forms:

Direct patch object (compat)
Wrapped form with CAS:
- { "patch": <JSON>, "expected_generation": <u64|null> }

If expected_generation is stale, the server returns 400 with a generation-conflict message.

GET /auth/profiles

List the auth profiles, backend profiles, and provider bindings for a realm.

string

required

Realm to read.

string | null

Optional profile selector accepted by the shared auth query shape.

Response

{
  "realm_id": "prod",
  "auth_profiles": [],
  "backend_profiles": [],
  "bindings": []
}

POST /auth/profiles

Store credentials for an existing binding-scoped auth profile. The binding must resolve to an auth profile whose source is managed_store; inline, env, external resolver, platform-default, command, and file-descriptor sources are configured outside this endpoint.

Request

{
  "realm_id": "prod",
  "binding_id": "openai",
  "profile_id": "prod_openai",
  "provider": "openai",
  "auth_method": "api_key",
  "secret": "sk-..."
}

Response (201 Created)

{
  "realm_id": "prod",
  "binding_id": "openai",
  "auth_binding": {
    "realm": "prod",
    "binding": "openai",
    "profile": "prod_openai"
  },
  "profile_id": "prod_openai",
  "provider": "openai",
  "auth_method": "api_key",
  "stored": true
}

string

required

Realm containing the binding.

string

required

Binding whose configured auth profile will receive the stored credential.

string | null

Optional explicit profile override for the binding.

string

required

Provider expected from the resolved auth profile.

string

required

Stored-secret method: "api_key", "azure_api_key", or "static_bearer".

string

required

Secret material to persist in the token store.

GET /auth/bindings/{binding_id}

Read the auth profile resolved by a binding.

string

required

Binding to resolve.

string

required

Realm containing the binding.

string | null

Optional explicit profile override for the binding.

DELETE /auth/bindings/{binding_id}

Clear stored credentials for the resolved binding-scoped auth profile.

string

required

Binding whose stored credentials should be cleared.

string

required

Realm containing the binding.

string | null

Optional explicit profile override for the binding.

POST /auth/bindings/{binding_id}/test

Resolve a binding through the provider registry and report whether credential material or a dynamic authorizer is available.

Request

{
  "realm_id": "prod",
  "profile_id": "prod_openai"
}

string

required

Binding to test.

string

required

Realm containing the binding.

string | null

Optional explicit profile override for the binding.

Begin a loopback OAuth login. The server owns the OAuth state and PKCE verifier.

Request

{
  "provider": "anthropic",
  "redirect_uri": "http://127.0.0.1:53682/callback",
  "realm_id": "prod",
  "binding_id": "anthropic",
  "profile_id": "claude_oauth"
}

string

required

Configured credential-owner realm; the server’s active realm is not an automatic substitute.

string

required

Configured binding to receive the OAuth credentials.

string | null

Optional explicit auth profile override.

Start and complete must address the same configured credential owner/binding/profile. See authentication setup. Complete a loopback OAuth login and store the resulting tokens under an explicit binding-scoped AuthBindingRef.

Request

{
  "provider": "anthropic",
  "code": "provider-code",
  "state": "state-from-start",
  "redirect_uri": "http://127.0.0.1:53682/callback",
  "realm_id": "prod",
  "binding_id": "anthropic",
  "profile_id": "claude_oauth"
}

string

required

Realm containing the binding.

string

required

Binding that owns the stored OAuth tokens.

string | null

Optional explicit profile override for the binding.

Begin a device-code OAuth login.

Request

{
  "provider": "google",
  "realm_id": "prod",
  "binding_id": "google",
  "profile_id": "gemini_oauth"
}

string

required

Configured credential-owner realm, explicitly supplied even when it matches the server’s active realm.

string

required

Configured binding to receive the device-flow credentials.

string | null

Optional explicit auth profile override.

Use that same credential owner/binding/profile for device completion; the example explicitly selects gemini_oauth in both requests. Poll one device-code OAuth completion attempt and, when ready, store the tokens under an explicit binding-scoped AuthBindingRef.

Request

{
  "provider": "google",
  "device_code": "device-code-from-start",
  "realm_id": "prod",
  "binding_id": "google",
  "profile_id": "gemini_oauth"
}

Returns 202 with { "state": "pending" } when the provider has not finished, 429 with { "state": "slow_down" } when the caller should back off, and 200 with a ready payload after tokens are persisted.

GET /auth/bindings/{binding_id}/status

Read binding-scoped auth status. The response includes the flattened binding identity plus profile_id, provider, auth_method, public state, expiration, refresh timestamp, account ID, and refresh-token presence.

string

required

Binding whose status should be read.

string

required

Realm containing the binding.

string | null

Optional explicit profile override for the binding.

POST /auth/bindings/{binding_id}/logout

Clear stored credentials for the binding and publish the auth lifecycle release.

string

required

Binding to log out.

string

required

Realm containing the binding.

string | null

Optional explicit profile override for the binding.

GET /realms

List configured realm summaries.

GET /realms/{id}

Read one realm connection set.

POST /comms/send

Push a canonical comms command into a running session. Requires the comms feature.

{
  "session_id": "01936f8a-7b2c-7000-8000-000000000001",
  "kind": "peer_message",
  "to": "01936f8a-7b2c-7000-8000-000000000002",
  "body": "Please review the latest diff",
  "handling_mode": "queue"
}

{
  "kind": "peer_message_sent",
  "envelope_id": "01936f8a-7b2c-7000-8000-000000000003",
  "delivery": "acked"
}

Closed request variants

CommsSendParams is a flat, kind-tagged union, not a shared bag of optional fields. Every variant requires a string session_id identifying the sending or receiving local session and rejects unknown fields. to is a canonical peer ID, never a display name.

`kind`	Required fields in addition to `session_id` and `kind`	Optional fields
`input`	`body` (string)	`blocks`, `source`, `stream`, `handling_mode`, `allow_self_session`
`peer_message`	`to`, `body` (string)	`blocks`, `content_taint`, `handling_mode`
`peer_lifecycle`	`to`, `lifecycle_kind`, `params`	None
`peer_request`	`to`, `intent`, `params`	`blocks`, `content_taint`, `handling_mode`, `stream`
`peer_response`	`to`, `in_reply_to`, `status`	`result`, `blocks`, `content_taint`, `handling_mode`

blocks is a typed ContentBlock array, not arbitrary JSON.
source belongs only to input: "tcp", "uds", "stdin", "webhook", or "rpc" (default "rpc"). It is not a free-text source label.
stream accepts "none" (default) or "reserve_interaction" on input and peer_request.
allow_self_session is an input-only boolean, default false.
content_taint is the typed SendTaintOverride on content-bearing peer variants; omission inherits the runtime’s outbound declaration.
handling_mode accepts "queue" or "steer". Omission/null defaults to "queue" for input, peer_message, and peer_request. It is forbidden on machine-classified progress responses. A terminal peer_response may specify it or inherit the recorded inbound request’s mode and requires that recorded request to still be repliable.

peer_message is the ordinary collaboration primitive. peer_lifecycle is a one-way topology notification: its lifecycle_kind is "mob.peer_added", "mob.peer_retired", "mob.peer_unwired", or "mob.dismiss". mob.dismiss is supervisor-directed; accepting that enum value does not grant the caller dismissal authority. Its required CommsPeerLifecycleParams object contains peer (string) and optional role, description, and typed peer_spec (BridgePeerSpec). peer_request is a structured ask with correlated replies. Its closed intent vocabulary is "supervisor.bridge" or "checksum_token", not arbitrary application labels such as "review" or "delegate". Required params must match the intent: a typed BridgeCommand for supervisor.bridge, or {"subject":"..."} for checksum_token. peer_response.in_reply_to is the request correlation ID. status accepts "accepted", "completed", or "failed". Optional result is a typed BridgeReply or a checksum result {"request_intent":"checksum_token","request_subject":"...","token":"..."}, not a free-form object. The canonical bridge shapes are meerkat_contracts::wire::supervisor_bridge::{BridgeCommand, BridgeReply, BridgePeerSpec} and their generated schema definitions.

Send receipts

Success returns HTTP 200 with a CommsSendResult selected by kind:

Result `kind`	Fields
`input_accepted`	`interaction_id`, `stream_reserved`
`peer_message_sent`	`envelope_id`, `delivery`
`peer_lifecycle_sent`	`envelope_id`, `delivery`
`peer_request_sent`	`envelope_id`, `interaction_id`, `request_id` (same value as `envelope_id`), `stream_reserved`, `delivery`
`peer_response_sent`	`envelope_id`, `in_reply_to`, `delivery`

delivery records the selected transport’s strongest proven delivery fact: acked, volatile_handed_off, queued, or a durably_resolved object with its typed ingress outcome. An acknowledgement does not prove completion of the recipient’s agent turn; a queued send does not prove receiver admission. This is distinct from the webhook routes’ 202/{"queued":true} admission response.

Unlike the two webhook ingress routes (which optionally check X-Webhook-Secret against RKAT_WEBHOOK_SECRET), /comms/send has no authentication. It is intended for trusted internal callers that already know the session ID.

GET /comms/peers

List discoverable peers for a session. Requires the comms feature.

string

required

Session ID to query peers for.

Response

{
  "peers": [
    {
      "peer_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "reviewer",
      "address": {
        "transport": "tcp",
        "endpoint": "127.0.0.1:4201"
      },
      "source": "trusted",
      "sendable_kinds": ["peer_message", "peer_request", "peer_response"],
      "capabilities": {
        "version": 1,
        "extensions": {"review": true}
      },
      "meta": {
        "description": "Reviews pull requests",
        "labels": {"role": "reviewer"}
      }
    },
    {
      "peer_id": "550e8400-e29b-41d4-a716-446655440002",
      "name": "coordinator",
      "address": {
        "transport": "inproc",
        "endpoint": "coordinator"
      },
      "source": "inproc",
      "sendable_kinds": ["peer_message", "peer_request", "peer_response"],
      "capabilities": {"version": 1, "extensions": {}},
      "meta": {}
    }
  ]
}

peer_id is the canonical routing value accepted by POST /comms/send; name is display-only and need not be unique. address is a typed {transport, endpoint} object, while source, sendable_kinds, capabilities, and meta describe discovery provenance and supported use.

Error responses

The ordinary REST ApiError adapter returns an HTTP status and a JSON envelope:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status	Code	When
400	`BAD_REQUEST`	Invalid parameters, session ID mismatch, keep_alive without comms
401	`UNAUTHORIZED`	Missing or invalid webhook secret
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Operation conflicts with current state
409	`DUPLICATE_INPUT`	Duplicate runtime input; response also carries top-level `existing_id`
409	`DUPLICATE_REQUEST_ID`	Request ID is already in flight
410	`GONE`	Resource is no longer available
499	`REQUEST_CANCELLED`	Request cancellation won before committed success; may include `details`
500	`CONFIGURATION_ERROR`	Server/configuration resolution failure
500	`AGENT_ERROR`	LLM provider error, tool dispatch failure, agent loop error
500	`INTERNAL_ERROR`	Store initialization failure, unexpected server error
503	`SERVICE_UNAVAILABLE`	Required service or capacity is unavailable

The adapter’s data-bearing bad-request/internal variants use HTTP 400/500 with a route-supplied typed code and details. Other route-specific typed projections retain their own codes and statuses. This table is not the canonical cross-surface ErrorCode index applied wholesale: for example, create-time SessionError::Busy currently maps to BAD_REQUEST/400, not a universal SESSION_BUSY/409. Do not require this envelope on every failure. Auth routes may return only {"error":"..."}; webhook admission has route-specific error projections, and framework JSON/path extraction errors can use different bodies. For a session that was durably created but whose first turn failed, the server returns SESSION_CREATED_WITH_TURN_FAILURE with resumable session identity in details. A genuinely unknown provider failure now runs the bounded retry policy; when that policy is exhausted, details.error.kind is retry_exhausted rather than llm_failure. Clients that branch on this nested kind should accept the new value. Known non-retryable LLM failures can still use llm_failure.

{
  "error": "Session not found: 01936f8a-7b2c-7000-8000-000000000099",
  "code": "NOT_FOUND"
}

{
  "error": "Session ID mismatch: path=abc body=def",
  "code": "BAD_REQUEST"
}

Notes

Keep-alive mode requires keep_alive: true and a comms_name. If keep_alive is requested but the binary was not compiled with comms support, the server returns a BAD_REQUEST error.

POST /sessions/{id}/external-events queues a runtime-backed external event. It is a queue-only admission path, not a second direct execution loop.

hooks_override allows per-request hook overrides including adding extra hook entries and disabling specific hooks by ID. See Hooks for the HookRunOverrides schema.

​Getting started

​Runtime scope

​Endpoint overview

​Request cancellation

​Configuration

​Endpoints

​POST /help

​POST /sessions

​Request fields

​Response fields

​GET /sessions//history

​POST /sessions/{id}/system_context

​POST /sessions/{id}/system_prompt

​GET /sessions

​POST /sessions/{id}/messages

​Request fields

​Response fields

​POST /sessions/{id}/interrupt

​POST /requests/{request_id}/cancel

​DELETE /sessions/{id}

​POST /sessions/{id}/external-events

​POST /sessions/{id}/peer-response-terminal

​GET /sessions/{id}

​GET /sessions/{id}/events

​GET /skills

​GET /health

​GET /runtime/host_info

​GET /runtime/capabilities

​GET /runtime/health

​GET /models/catalog

​GET /capabilities

​GET /config

​PUT /config

​PATCH /config

​GET /auth/profiles

​POST /auth/profiles

​GET /auth/bindings/{binding_id}

​DELETE /auth/bindings/{binding_id}

​POST /auth/bindings/{binding_id}/test

​POST /auth/login/start

​POST /auth/login/complete

​POST /auth/login/device/start

​POST /auth/login/device/complete

​GET /auth/bindings/{binding_id}/status

​POST /auth/bindings/{binding_id}/logout

​GET /realms

​GET /realms/{id}

​POST /comms/send

​Closed request variants

​Send receipts

​GET /comms/peers

​Error responses

​Notes

Getting started

Runtime scope

Endpoint overview

Request cancellation

Configuration

Endpoints

POST /help

POST /sessions

Request fields

Response fields

GET /sessions//history

POST /sessions/{id}/system_context

POST /sessions/{id}/system_prompt

GET /sessions

POST /sessions/{id}/messages

Request fields

Response fields

POST /sessions/{id}/interrupt

POST /requests/{request_id}/cancel

DELETE /sessions/{id}

POST /sessions/{id}/external-events

POST /sessions/{id}/peer-response-terminal

GET /sessions/{id}

GET /sessions/{id}/events

GET /skills

GET /health

GET /runtime/host_info

GET /runtime/capabilities

GET /runtime/health

GET /models/catalog

GET /capabilities

GET /config

PUT /config

PATCH /config

GET /auth/profiles

POST /auth/profiles

GET /auth/bindings/{binding_id}

DELETE /auth/bindings/{binding_id}

POST /auth/bindings/{binding_id}/test

POST /auth/login/start

POST /auth/login/complete

POST /auth/login/device/start

POST /auth/login/device/complete

GET /auth/bindings/{binding_id}/status

POST /auth/bindings/{binding_id}/logout

GET /realms

GET /realms/{id}

POST /comms/send

Closed request variants

Send receipts

GET /comms/peers

Error responses

Notes