Skip to main content
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

1

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:
2

Start the server

In that same configured terminal, start the installed binary:
On 0.9.15 and earlier, on a new machine or a new account, first create the server’s default context directory (on Linux, by default mkdir -p ~/.local/share/meerkat/rest; the error names the directory on every system) or start the server with --context-root <an existing directory>: in those releases, while that directory is missing, a POST /sessions that carries no system_prompt, such as the request in the next step, is answered HTTP 500 (see Known limitations of 0.9.15 in the CHANGELOG). From 0.9.16 the step is not needed: a default context directory that does not exist holds no project instructions, and the session is created.
3

Send a request

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

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. OS process confinement flags (see OS process confinement):
They replace the realm’s composed [confinement] for every launch kind of this process. The workspace preset confines each launch to --context-root; without --context-root the server refuses to start with it. A start in which a confined process could change the server’s realm state or user config document is refused (see the host’s own inputs). At startup the server logs each launch kind’s requested and effective confinement and warns for each required kind its platform cannot confine.
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. 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.GET /workgraph/items, /workgraph/ready and /workgraph/snapshot return the page fields of the matching RPC methods: a response that ended early has truncated: true and a next_cursor to pass back as the cursor query parameter (a malformed or foreign cursor is a 400). GET /workgraph/events reports truncated and next_after_seq for after_seq.

Request cancellation

REST request cancellation is opt-in and request-ID based.
Known issue, noted 2026-11-13: in Meerkat 0.8.0 through 0.9.14, cancelling a request that is still waiting behind another turn can permanently destroy the mobs of the session it was queued for. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.
  • 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

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:
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
Returns a HelpResponse with the answer text and any plan metadata requested by the input.

POST /sessions

Create and run a new session.

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.
string | null
default:"null"
From 0.9.15; an older server ignores the field. The 0.9.15 Python and TypeScript SDKs refuse to send it to an older server, so nothing is sent. The session’s provider-neutral reasoning effort level: none, minimal, low, medium, high, xhigh or max (see Reasoning effort). It is the same setting as provider_params.reasoning_effort; a request that gives both must give the same level. A level the model or its route does not accept is refused with HTTP 400, code INVALID_PARAMS and details {"kind": "reasoning_effort_refused", "retryable": false, "reasoning_effort_refusal": {...}}, before any provider request.
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/{id}/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
History is returned oldest-to-newest and reflects the last committed session snapshot only. block_assistant rows committed by 0.8.45 or later carry assistant_message_id, the same id the message’s live SSE events carried; join live output to history by that id. Rows the realtime transcript materializer commits carry realtime_origin instead, whose provider_item_ids match the provider item ids on the live transport’s realtime observations. See assistant message identity.

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
Response

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
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
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.

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. Known issue, noted 2026-11-13: in Meerkat 0.7.0 through 0.9.14, a turn that cannot be started can permanently destroy the mobs its session owns. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.
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.
TurnMetadataOverride | null
default:"preserve"
From 0.9.15; an older server ignores the field. The 0.9.15 Python and TypeScript SDKs refuse to send it to an older server, so nothing is sent. The session’s provider-neutral reasoning effort level from this message on: a level ("high", or {"action":"set","value":"high"}) sets it, {"action":"clear"} removes it, and omission/null keeps the level the session recorded. On a session this server does not hold live, a level the model or its route does not accept is refused exactly as on POST /sessions: HTTP 400, code INVALID_PARAMS and the reasoning_effort_refused details. The stored session is unchanged. A message that names this field rebuilds the session, like one that names model or max_tokens: while this server holds the session live, such a message is answered HTTP 500 session is busy and changes nothing. So on REST a provider-neutral level can be set only when the session is created (POST /sessions) or on a session this server does not hold live. On a live session a message that names the level, or a model, is not served: it is refused at once, whether or not a turn is running, and nothing is stored or queued for it; a turn that is running and the messages queued behind it go on. In 0.9.15 the answer is HTTP 500 with code INTERNAL_ERROR and a text that says the session is busy; read it as “not served on a live session”, and do not rely on that status or code staying. It is not an answer to retry when the session is idle: sending the message again while the server holds the session is refused the same way. The typed busy answer of JSON-RPC (reasoning_effort_change_needs_idle_session) does not apply to REST. provider_params is not a member of this request and is not read here: the field is the only form of the level on a message.
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
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 /sessions/{id}/runs/{run_id}/stop

Stop one exact run and terminalize every input already bound to it, including durable steers that joined it. Learn the run id from the run_started event (identity.run_id). The response is the same StopRunResult as the RPC turn/stop_run method.
Request
Response
receipt.outcome is stopped, not_current (the run is no longer current; nothing was touched), or not_stoppable (a runtime stop or teardown owns the still-bound run). A run a store fence gap suspended, one a restart left open that has not resumed yet, or one whose session store’s writer is stopped, is stopped without waiting: stopped with no contributors, and its inputs end cancelled when the runtime settles it (once the store takes writes again, after a gap; read their outcome later). A malformed run_id is 400. POST /mob/{id}/members/{agent_identity}/runs/{run_id}/stop stops one exact run of a mob member and returns MobStopMemberRunResult ({mob_id, agent_identity, receipt}) with the same receipt.

POST /requests/{request_id}/cancel

Cancel an uncommitted in-flight request that previously supplied X-Meerkat-Request-Id.
Known issue, noted 2026-11-13: in Meerkat 0.8.0 through 0.9.14, cancelling a request that is still waiting behind another turn can permanently destroy the mobs of the session it was queued for. See the known issue on the 0.9.14 release page for the affected releases, the cases and what to do.
Response
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
Returns 404 if the session is not found.

POST /sessions/{id}/external-events

Queue an external event through the runtime-backed admission path.
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: the event waits for the session’s next turn. That holds only while the session is idle. While the session is running a turn or still finishing one, including the instant after that turn’s call (or the create call) has answered, an event admitted then is taken as soon as that turn ends, as a new turn: the session makes at least one model call, in a run that no caller started. The answer is 202 and {"queued": true} in both cases (see Known limitations of 0.9.15 in the CHANGELOG). 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
Optional caller key that makes a retry safe. A retry under the same key admits nothing new and answers 202 {"queued": true} again. The same key with other event content answers 409 with {"error", "code": "INPUT_IDEMPOTENCY_CONFLICT", "existing_id"}; the first admission stands. The key is scoped to the session, shared with the RPC session/external_event method, and kept for the session’s life. Object key order inside payload does not matter. Canonical text: non-empty, no surrounding whitespace, no control characters, at most 256 bytes (400 otherwise). A server older than 0.9.5 ignores the field, so check the server version before relying on it.
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).

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
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

GET /sessions/{id}/events

Server-Sent Events (SSE) stream for real-time updates. Event types: 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
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)
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)
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. A PUT or PATCH that would administer a section the host administers in the document itself returns 400 with code CONFIG_WRITE_REFUSED, and nothing is written. details.type names the section: governance_administration_required (change, remove or restate [governance]) or confinement_administration_required (add, change or remove [confinement], or add a credential command or change what one runs). A write that changes realm sections (a parent edge, or the user document’s [realm.global]) so that a realm would compose a different section is refused with the same types, and its message names the change and the realm, for example removing [realm.global] would change the [governance] section a realm whose own document states no parent and no [realm.global] composes.

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

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
Response (201 Created)
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
string
required
Binding to test.
string
required
Realm containing the binding.
string | null
Optional explicit profile override for the binding.

POST /auth/login/start

Begin a loopback OAuth login. The server owns the OAuth state and PKCE verifier.
Request
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.

POST /auth/login/complete

Complete a loopback OAuth login and store the resulting tokens under an explicit binding-scoped AuthBindingRef.
Request
string
required
Realm containing the binding.
string
required
Binding that owns the stored OAuth tokens.
string | null
Optional explicit profile override for the binding.
The same endpoints accept an MCP server target instead of a provider binding: {"mcp": {"server_name", "server_url", "oauth_account", "oauth_account_selection"}, ...} (the last two only name the configured selection), or a connector target, {"connector": {"slot", "issuer", "client", "resource", "scopes", "strategy_id", "account_selection"}, ...}. See Host-driven OAuth and Connector OAuth. Auth endpoint errors return {"error": "<text>", "reason": "<WireAuthErrorReason>"}. Branch on reason (for example slot_occupied, account_mismatch, attempt_missing, reauth_required, infrastructure), not on the text; status codes are unchanged. Some errors also carry a stable sub-kind in detail, for example upstream_timeout or upstream_timeout_after_code (reason upstream_failure) when a network stage of an MCP login got no answer within its bound. The reason commit_unsettled means a credential commit’s outcome is unknown (an MCP login’s commit did not report in time, the commit’s owner ended before it reported, or the commit failed and could not restore the previous credential): whether the credential landed is unknown until it settles, so read the status later, and log in again if a use is then refused for authorization. A failed credential commit of POST /auth/profiles carries its typed reason too, with a fixed error text.

POST /auth/login/cancel

Retire a pending MCP or connector OAuth attempt by its state. An MCP server must be configured; a connector attempt is named by its slot, {"connector": {"realm_id", "slot_id"}, "state"}. An MCP attempt may instead be named by the non-secret reference the RPC auth/status/get reports, {"mcp": {...}, "attempt_ref"}, never by both.
Request

POST /auth/login/device/start

Begin a device-code OAuth login.
Request
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.

POST /auth/login/device/complete

Poll one device-code OAuth completion attempt and, when ready, store the tokens under an explicit binding-scoped AuthBindingRef.
Request
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.

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.
  • 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 notification: its lifecycle_kind is a topology kind ("mob.peer_added", "mob.peer_retired", "mob.peer_unwired", "mob.dismiss") or a member-kickoff status kind ("mob.kickoff_pending", "mob.kickoff_starting", "mob.kickoff_started", "mob.kickoff_callback_pending", "mob.kickoff_failed", "mob.kickoff_cancelled"). Kickoff kinds reach the receiving agent as a visible lifecycle comms notice; none of them opens a request. 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: 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.

Send errors

A failed send returns HTTP 500 whose code and details.code name the failure with the JSON-RPC vocabulary: peer_not_found_or_not_trusted, peer_unreachable, peer_admission_dropped, peer_input_rejected, peer_wake_refused, send_ambiguous or send_failed. peer_wake_refused means the peer is a seated member whose wake was refused or did not finish: nothing was delivered, its details carry the envelope_id, the typed refusal (tagged on kind) and retryable, and a retry cannot duplicate the message. send_ambiguous means the envelope may already be delivered: its details carry the envelope_id, retry_safe: false and required_action: "reconcile". Reconcile by that envelope before any new attempt; a retry can duplicate it.
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
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:
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. A reasoning_effort level that the model’s route does not accept answers HTTP 400 with code INVALID_PARAMS and details {"kind": "reasoning_effort_refused", "retryable": <bool>, "reasoning_effort_refusal": {...}}, the object JSON-RPC carries as error.data (see Reasoning effort refusal data). A refused session build and a turn that failed for the refusal answer the same way, on POST /sessions and on POST /sessions/{id}/messages alike. The refusal’s route, supported and facts are always present and are null when they have no value; they are never left out. When a refused turn belongs to the request that created its session, details also carries session_id, session_ref, session_created: true and resumable: true. 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. Both kinds carry the provider facts in details.error: provider, retryable and the typed reason. A retry_exhausted error has retryable: true (the class of the failure can succeed on a later attempt; it is no promise that it will) and the reason of the last failed attempt (a rate limit, a timeout, or a provider error such as server_overloaded); the fields and their values are those of the JSON-RPC turn error.

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.