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
--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):
[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.
Endpoint overview
This overview follows the generated OpenAPI artifact atartifacts/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.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.- send
X-Meerkat-Request-Id: <id>onPOST /sessionsorPOST /sessions/{id}/messages - call
POST /requests/{request_id}/cancelto cancel uncommitted in-flight work - duplicate in-flight request IDs are rejected
- 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
Server configuration details
REST configuration is realm-scoped:API keys are provided via environment variables:
- macOS:
~/Library/Application Support/meerkat/realms/<realm>/config.toml - Linux:
~/.local/share/meerkat/realms/<realm>/config.toml - Windows:
%APPDATA%\\meerkat\\realms\\<realm>\\config.toml
realm_manifest.json (backend pinning) and config_state.json (generation CAS state).Key sections:ANTHROPIC_API_KEYOPENAI_API_KEYGOOGLE_API_KEY
Endpoints
POST /help
Ask Meerkat usage help with the embedded platform skill.Request
HelpResponse with the answer text and any plan metadata requested by the input.
POST /sessions
Create and run a new session.Request fields
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.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).
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.
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.Provider:
"anthropic", "openai", "gemini", "self_hosted", "other".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.JSON schema for structured output extraction (wrapper or raw schema).
Max retries for structured output validation.
null/omitted uses the server default on create and inherits the persisted session value on continue.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.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.Run-scoped hook overrides (see Hooks).
Enable built-in tools (task management, etc.). Omit to use factory defaults.
Enable shell tool (requires
enable_builtins). Omit to use factory defaults.Override schedule tools for this session. Omit to use factory defaults.
Override WorkGraph tools for this session. Omit to use factory defaults.
Response fields
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.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 ofGET /sessions/{id}.
Query parameters:
offset— skip this many messages from the start of the transcriptlimit— cap the number of returned messages
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 suppliestarget_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
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
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
Follow-up prompt as text or typed content blocks, for example
[{"type":"text","text":"Continue"}]. Media support is model/provider
dependent; see model capabilities.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).
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.
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.
Provider override for this turn. Typically inferred from
model. Used with model for mid-session provider switching.Max retries for structured output validation. Omit /
null to inherit the persisted session value on continue.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.Keep-alive override for this turn.
null = inherit persisted session intent, true = enable, false = disable.Response fields
Same shape asPOST /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 therun_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 suppliedX-Meerkat-Request-Id.
Response
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
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.Must be
"generic_json". The "peer_response_terminal" tag is reserved
and rejected here.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.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. Likeexternal-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
Required when
RKAT_WEBHOOK_SECRET is set on the server; omit only when
webhook-secret authentication is disabled.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
404 if skills are not enabled.
GET /health
Returns"ok" (HTTP 200). Use for liveness checks.
GET /runtime/host_info
Returns the read-onlyRuntimeHostInfo 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
ReturnsRuntimeHostCapabilities, a contract version plus boolean
RuntimeHostFeatureFlags. These host feature flags are distinct from the
generic status entries returned by GET /capabilities.
GET /runtime/health
ReturnsRuntimeHostHealth 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)
GET /capabilities
Returns runtime capabilities with status resolved against config.Response (abbreviated)
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:configgenerationrealm_idinstance_idbackendresolved_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> }
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.Response
POST /auth/profiles
Store credentials for an existing binding-scoped auth profile. The binding must resolve to an auth profile whose source ismanaged_store; inline, env,
external resolver, platform-default, command, and file-descriptor sources are
configured outside this endpoint.
Request
Response (201 Created)
GET /auth/bindings/{binding_id}
Read the auth profile resolved by a binding.DELETE /auth/bindings/{binding_id}
Clear stored credentials for the resolved binding-scoped auth profile.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
POST /auth/login/start
Begin a loopback OAuth login. The server owns the OAuth state and PKCE verifier.Request
Configured credential-owner realm; the server’s active realm is not an
automatic substitute.
POST /auth/login/complete
Complete a loopback OAuth login and store the resulting tokens under an explicit binding-scopedAuthBindingRef.
Request
{"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
Configured credential-owner realm, explicitly supplied even when it matches
the server’s active realm.
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-scopedAuthBindingRef.
Request
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 plusprofile_id, provider, auth_method, public state,
expiration, refresh timestamp, account ID, and refresh-token presence.
POST /auth/bindings/{binding_id}/logout
Clear stored credentials for the binding and publish the auth lifecycle release.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 thecomms 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.
blocksis a typedContentBlockarray, not arbitrary JSON.sourcebelongs only toinput:"tcp","uds","stdin","webhook", or"rpc"(default"rpc"). It is not a free-text source label.streamaccepts"none"(default) or"reserve_interaction"oninputandpeer_request.allow_self_sessionis an input-only boolean, defaultfalse.content_taintis the typedSendTaintOverrideon content-bearing peer variants; omission inherits the runtime’s outbound declaration.handling_modeaccepts"queue"or"steer". Omission/nulldefaults to"queue"forinput,peer_message, andpeer_request. It is forbidden on machine-classified progress responses. A terminalpeer_responsemay 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 HTTP200 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 HTTP500 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 thecomms feature.
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 RESTApiError 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.