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

Start the server

rkat-rest --realm team-alpha

Set API keys

Export the key for your chosen provider:

export ANTHROPIC_API_KEY="sk-..."
# or OPENAI_API_KEY, GOOGLE_API_KEY

Send a request

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

Runtime scope

rkat-rest accepts:

--realm <id>
--isolated
--instance <id>
--realm-backend <sqlite|jsonl>
--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.

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 staged runtime system context
`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`	`/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)
`GET`	`/mob/{id}/members/{agent_identity}/status`	Read member status (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`	`/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

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 read-only observability/operator lookup. Agents create, claim, update, link, evidence, and close WorkGraph items through WorkGraph tools inside sessions.

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-6"
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"
}

Request fields

prompt

string

required

The user prompt to send to the agent.

system_prompt

string | null

default:"null"

Override the system prompt for this session.

model

string | null

default:"config default"

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

provider

string | null

default:"inferred from model"

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

max_tokens

u32 | null

default:"config default"

Max tokens per turn.

output_schema

OutputSchema | null

default:"null"

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

structured_output_retries

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.

verbose

bool

default:"false"

Enable verbose event logging (server-side).

keep_alive

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.

comms_name

string | null

default:"null"

Agent name for inter-agent communication.

peer_meta

object | null

default:"null"

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

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": "assistant", "content": "Hi there." }
  ]
}

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

hooks_override

HookRunOverrides | null

default:"null"

Run-scoped hook overrides (see Hooks).

enable_builtins

bool | null

default:"null (factory default)"

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

enable_shell

bool | null

default:"null (factory default)"

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

enable_memory

bool | null

default:"null (factory default)"

Enable semantic memory. Omit to use factory defaults.

enable_schedule

bool | null

default:"null (factory default)"

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

enable_workgraph

bool | null

default:"null (factory default)"

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

Response fields

session_id

string

UUID of the created session.

text

string

The agent’s response text.

turns

u32

Number of LLM calls made.

tool_calls

u32

Number of tool calls executed.

usage

WireUsage

Token usage breakdown.

usage.input_tokens

u64

Input tokens consumed.

usage.output_tokens

u64

Output tokens generated.

usage.total_tokens

u64

Total tokens (input + output).

usage.cache_creation_tokens

u64 | null

Cache creation tokens (provider-specific).

usage.cache_read_tokens

u64 | null

Cache read tokens (provider-specific).

structured_output

object | null

Parsed structured output (when output_schema was provided).

schema_warnings

array | null

Schema compatibility warnings per provider.

Structured output example

{
  "prompt": "Extract the capital of France",
  "model": "claude-opus-4-6",
  "output_schema": {
    "schema": {
      "type": "object",
      "properties": {
        "country": {"type": "string"},
        "capital": {"type": "string"}
      },
      "required": ["country", "capital"]
    },
    "name": "capital_extraction",
    "strict": false,
    "compat": "lossy",
    "format": "meerkat_v1"
  },
  "structured_output_retries": 2
}

When output_schema is provided, the text field remains the committed main-turn assistant output. The extraction turn runs afterward and populates structured_output on success or extraction_error on failure.output_schema may be provided as a wrapper object (shown above) or as a raw JSON Schema object. The wrapper enables explicit compat/format settings.

GET /sessions

List sessions. Supports optional label filters via query parameters.

Response

{
  "sessions": [
    {
      "session_id": "01936f8a-7b2c-7000-8000-000000000001",
      "state": "idle",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

POST /sessions/{id}/messages

Continue an existing session.

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

Request fields

session_id

string

required

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

prompt

string

required

Follow-up prompt.

system_prompt

string | null

default:"null"

Override the system prompt.

model

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.

provider

string | null

default:"from session"

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

max_tokens

u32 | null

default:"from session"

Max tokens override for this turn.

output_schema

OutputSchema | null

default:"null"

Structured output schema for this turn.

structured_output_retries

u32 | null

default:"null"

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

verbose

bool

default:"false"

Enable verbose event logging.

keep_alive

bool | null

default:"null"

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

comms_name

string | null

default:"from session"

Agent name for comms.

hooks_override

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": true}

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/sid_abc/external-events \
  -H "Content-Type: application/json" \
  -d '{"alert": "CPU spike", "host": "web-03"}'

This route keeps the optional RKAT_WEBHOOK_SECRET header auth used for webhook delivery, but the admitted event now flows through runtime input acceptance instead of a surface-local injector path.

(body)

any JSON

required

Any JSON payload. Pretty-printed and injected as an event into the agent’s inbox.

X-Webhook-Secret

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.

curl -X POST http://localhost:8080/sessions/sid_abc/peer-response-terminal \
  -H "Content-Type: application/json" \
  -d '{
    "peer_id": "00000000-0000-4000-8000-000000000161",
    "display_name": "analyst",
    "request_id": "00000000-0000-4000-8000-000000000162",
    "status": "completed",
    "result": {"token": "silver harbor"}
  }'

peer_id

string

required

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

display_name

string

Optional presentation label.

request_id

string

required

Peer correlation ID for the request this terminal response completes.

status

string

required

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

result

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
`done`	Emitted when the broadcast channel closes

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 /models/catalog

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

Response (abbreviated)

{
  "contract_version": "0.6.5",
  "providers": [
    {
      "provider": "anthropic",
      "default_model_id": "claude-opus-4-7",
      "models": [
        {
          "id": "claude-opus-4-7",
          "display_name": "Claude Opus 4.7",
          "tier": "recommended",
          "context_window": 1000000,
          "max_output_tokens": 128000,
          "profile": {
            "model_family": "claude-opus-4",
            "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": 6, "patch": 5},
  "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 capabilities: sessions, streaming, structured_output, hooks, builtins, shell, comms, memory_store, schedule, work_graph, session_store, session_compaction, skills, mcp_live. See the RPC capabilities endpoint for the complete example.

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.

realm_id

string

required

Realm to read.

profile_id

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
}

realm_id

string

required

Realm containing the binding.

binding_id

string

required

Binding whose configured auth profile will receive the stored credential.

profile_id

string | null

Optional explicit profile override for the binding.

provider

string

required

Provider expected from the resolved auth profile.

auth_method

string

required

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

secret

string

required

Secret material to persist in the token store.

GET /auth/bindings/{binding_id}

Read the auth profile resolved by a binding.

binding_id

string

required

Binding to resolve.

realm_id

string

required

Realm containing the binding.

profile_id

string | null

Optional explicit profile override for the binding.

DELETE /auth/bindings/{binding_id}

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

binding_id

string

required

Binding whose stored credentials should be cleared.

realm_id

string

required

Realm containing the binding.

profile_id

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

binding_id

string

required

Binding to test.

realm_id

string

required

Realm containing the binding.

profile_id

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

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

realm_id

string

required

Realm containing the binding.

binding_id

string

required

Binding that owns the stored OAuth tokens.

profile_id

string | null

Optional explicit profile override for the binding.

Begin a device-code OAuth login.

Request

{
  "provider": "google"
}

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.

binding_id

string

required

Binding whose status should be read.

realm_id

string

required

Realm containing the binding.

profile_id

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.

binding_id

string

required

Binding to log out.

realm_id

string

required

Realm containing the binding.

profile_id

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": "reviewer",
  "body": "Please review the latest diff",
  "handling_mode": "queue",
  "source": "ci-pipeline"
}

session_id

string

required

Session ID to dispatch the comms command to.

kind

string

required

Command kind: "input", "peer_message", "peer_lifecycle", "peer_request", or "peer_response".

string | null

Peer name to send to (required for peer_message, peer_lifecycle, peer_request, and peer_response).

body

string | null

Message body (required for input and peer_message).

handling_mode

string | null

Handling mode for input, peer_message, peer_request, and peer_response. Local callers must provide "queue" or "steer".

peer_message is the default collaboration primitive. peer_lifecycle is a one-way topology notification. peer_request is only a structured ask with correlated replies.

lifecycle_kind

string | null

Lifecycle event kind: "mob.peer_added", "mob.peer_retired", or "mob.peer_unwired" (required for peer_lifecycle).

intent

string | null

Request intent (required for peer_request, e.g. "review", "delegate").

params

object | null

Request parameters (optional for peer_request).

in_reply_to

string | null

ID of the request being responded to (required for peer_response).

status

string | null

Response status: "accepted", "completed", or "failed" (for peer_response).

result

object | null

Response result data (optional for peer_response).

source

string | null

Optional source label.

stream

string | null

Optional input stream mode: "none" or "reserve_interaction" (for input and peer_request).

allow_self_session

bool | null

Allow the session to send a message to itself (default: false).

Unlike POST /sessions/{id}/external-events (which uses RKAT_WEBHOOK_SECRET header auth), /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.

session_id

string

required

Session ID to query peers for.

Response

{
  "peers": [
    {"name": "reviewer", "address": "127.0.0.1:4201"},
    {"name": "coordinator", "address": "inproc"}
  ]
}

Error responses

All errors are returned as JSON with an HTTP status code:

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

HTTP Status	Code	When
400	`BAD_REQUEST`	Invalid parameters, session ID mismatch, keep_alive without comms
403	`HOOK_DENIED`	Hook blocked the operation
404	`SESSION_NOT_FOUND`	Session does not exist
404	`SKILL_NOT_FOUND`	Requested skill does not exist
409	`SESSION_BUSY`	Turn already in progress
409	`SESSION_NOT_RUNNING`	Session not in running state
422	`SKILL_RESOLUTION_FAILED`	Skill resolution error
429	`BUDGET_EXHAUSTED`	Resource limits reached
500	`AGENT_ERROR`	LLM provider error, tool dispatch failure, agent loop error
500	`INTERNAL_ERROR`	Store initialization failure, unexpected server error
501	`CAPABILITY_UNAVAILABLE`	Required capability not compiled in or disabled
502	`PROVIDER_ERROR`	LLM provider issue (missing key, auth failure)

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

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.

CLI

APIs

Documentation Index

​Getting started

​Runtime scope

​Endpoint overview

​Request cancellation

​Configuration

​Endpoints

​POST /help

​POST /sessions

​Request fields

​GET /sessions//history

​Response fields

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

​GET /comms/peers

​Error responses

​Notes

Getting started

Runtime scope

Endpoint overview

Request cancellation

Configuration

Endpoints

POST /help

POST /sessions

Request fields

GET /sessions//history

Response fields

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

GET /comms/peers

Error responses

Notes