HTTP API

Local apps/clankie service on http://127.0.0.1:4310. There is no HTML index: / is 404 and GET /health is the public probe.

Most other routes take an Authorization: Bearer <token> header. Pairing redeem/complete use their one-time offer secrets instead. Persistent tokens live in the credential broker (Keychain service bot.clankie.credentials):

Discord-lane routes 403 if the bearer is the console captain token (steer source api). Import this file in Yaak (Settings → Import/Export) or run apps/clankie/scripts/setup-yaak.py.

Base URL http://127.0.0.1:4310 · version 0.2.0 · the raw document is openapi.yaml.

This is the local contract on your machine. From the internet only the public network surface is reachable, through api.clankie.bot, and your machine still decides every grant.

Bearers

Routes

Health

GET /health — Public liveness

Bearer: none

Operator

GET /v1/herdr — Running service's worker-runtime binding

Pending settings do not change this binding until service restart.

Bearer: operator

GET /v1/discord/presence-status — Operator presence snapshot

Phase and counts only. What clankie status reads.

Bearer: operator

POST /v1/discord/user-session/opt-in — Record user-session ToS acceptance

Bearer: operator

Request body (required JSON)

{
  "schemaVersion": 1,
  "characterId": "clankie",
  "acknowledgement": "I accept Discord user-session transport risk on my account.",
  "guildIds": [
    "123456789012345678"
  ],
  "channelIds": [
    "123456789012345678"
  ],
  "dmPolicy": "deny"
}

DELETE /v1/discord/user-session/opt-in — Revoke the active user-session opt-in

Bearer: operator

GET /v1/discord/stream-watch — Latest observed Discord screen shares

Metadata plus up to four chronological stills. Raw video is never stored.

Bearer: captain or operator

GET /v1/discord/voice-transcripts — Page through retained Discord voice transcripts

Captain bearer only. Exact speech is returned only while discord.voiceTranscriptLoggingEnabled is enabled; otherwise the route returns an empty page with enabled: false.

Bearer: captain

GET /operator/v1/voice-chat — Open a private local voice chat

Upgrades to a WebSocket for captain bearers whose source lane is api. Binary client frames are 24 kHz mono signed 16-bit little-endian PCM; {"schemaVersion":1,"type":"commit"} ends one utterance. Binary server frames use the same PCM format. JSON server frames report status, attributed transcript, response_done, or error events. Raw audio is not retained. The realtime room can call the captain through the shared operator-conversation service when work is required.

Bearer: captain

Captain

POST /v1/captain/channel-turns — One Discord message becomes one captain turn

Bearer: discord text or discord voice

Request body (required JSON)

{
  "schemaVersion": 1,
  "deliveryId": "yaak-delivery-1",
  "identity": {
    "presenceSessionId": "replace-me",
    "correlationId": "yaak-1",
    "profileHash": "unversioned",
    "characterId": "clankie",
    "credentialRef": "discord_bot",
    "transportKind": "bot"
  },
  "trigger": {
    "kind": "message",
    "id": "1",
    "channelId": "123456789012345679",
    "actorId": "123456789012345680",
    "body": "hello from Yaak"
  }
}

POST /v1/captain/presence — Report captain lease heartbeat

Bearer: captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "type": "captain.heartbeat",
  "eventId": "yaak-hb-1",
  "leaseId": "replace-me",
  "generationId": "replace-me",
  "occurredAt": "2026-08-15T20:00:00.000Z"
}

POST /operator/v1/dispatch — Operator conversation contract

One route, discriminated op: list, roster, get, create, fork, close, send, cancel, replay, tail, autonomy, terminal_tail. The TUI and relay both speak this. Seat scopes identify Herdr direct-send/projection threads. cancel interrupts one accepted run: the captain aborts the live model turn and the durable log settles that run as cancelled. fork clones the current Pi leaf into an ephemeral child conversation. Pane-scoped send and state_stance requests qualify their pane ID with the source socket. A mismatched send loses its pane association; a mismatched stance returns 409 without changing a worker.

Bearer: captain

Request body (required JSON)

List conversations

{
  "op": "list",
  "schemaVersion": 1
}

List live Herdr seats

{
  "op": "roster",
  "schemaVersion": 1
}

Create a global conversation

{
  "op": "create",
  "schemaVersion": 1,
  "scope": {
    "kind": "global"
  },
  "title": "Yaak probe"
}

Get one conversation

{
  "op": "get",
  "schemaVersion": 1,
  "conversationId": "replace-me"
}

Fork an ephemeral side conversation

{
  "op": "fork",
  "schemaVersion": 1,
  "parentConversationId": "replace-me"
}

Close a non-default conversation or discard a side fork

{
  "op": "close",
  "schemaVersion": 1,
  "conversationId": "replace-me"
}

Send a message turn

{
  "op": "send",
  "schemaVersion": 1,
  "turn": {
    "schemaVersion": 1,
    "kind": "message",
    "conversationId": "replace-me",
    "surfaceClientId": "yaak",
    "expectedRevision": 0,
    "message": "ping from Yaak"
  }
}

Replay a page

{
  "op": "replay",
  "schemaVersion": 1,
  "replay": {
    "schemaVersion": 1,
    "conversationId": "replace-me",
    "surfaceClientId": "yaak",
    "limit": 50
  }
}

Read autonomy state for one conversation

{
  "op": "autonomy",
  "schemaVersion": 1,
  "conversationId": "replace-me",
  "command": {
    "action": "status"
  }
}

GET /captain/v1/lanes — Observable captain lanes

Bearer: captain

GET /v1/captain/turn-metrics — Recent settled captain turns

Counters, execution identity and reported usage for recent settled operator and Discord turns, newest first, from the durable turn-settled.jsonl the captain appends. Never a transcript, tool argument, tool output or credential.

execution is the model, provider and effort that actually ran the turn, captured as it executed rather than read back from configuration. usage is totalTokens summed over the assistant messages the provider reported plus reports, the number that contributed. Both are null when unknown — a turn settled before the capture existed, or a provider that reported nothing. Null never means zero, and contextTokensStart / contextTokensEnd are context occupancy, never usage or a charge.

Bearer: operator

GET /v1/captain/prompt — The system prompt a lane's session starts from

Plain text, for a seat launcher in another harness. sections is a comma-separated subset of identity, persona, reach, address, model; omitted, it is the four a pi session starts with (model is the per-run card, asked for by name). The lane must be the bearer's own — the operator credential and the console captain token are operator, a Discord bridge bearer is the lane it serves.

Bearer: operator or captain

GET /v1/captain/memory-card — The memory card that lane's next run injects

Plain text, for a per-turn hook. Filtered by lane the same way the pi session's own injection is: operator-private episodes reach only the operator lane. Empty when the lane has recalled nothing yet. The lane must be the bearer's own.

Bearer: operator or captain

GET /v1/mcp — Server-to-client notification stream for an open session

Requires mcp-session-id; the bearer must resolve to the session's lane.

Bearer: operator or captain or discord text or discord voice

POST /v1/mcp — A lane's tool bank over streamable-HTTP MCP

Streamable-HTTP MCP over Clankie's authored tool registry. The bearer selects the lane and the lane selects the tools: the operator credential and the console captain token are operator, a Discord bridge bearer is the lane it serves, and a connection lists exactly that lane's authority plan (authored tools, the browser catalog, and the connected-service tools that lane may reach). An initialize POST opens a session and returns its id in mcp-session-id; every later request must carry that header and resolve to the same lane. DELETE ends the session. clankie mcp is the stdio bridge to this route (ADR 0152).

Bearer: operator or captain or discord text or discord voice

DELETE /v1/mcp — End an MCP session

Bearer: operator or captain or discord text or discord voice

GET /v1/seat/events — Long-poll the seat's outbox

Wakes, herdr completion watches, and room escalations queued for a bound head (ADR 0152). Polling is what binds the seat: clankie mcp asks again the moment a poll returns and pushes each event into the session as a channel notification. Operator bearer only; a Discord bridge bearer is 403. wait is capped at 30000 ms.

Bearer: operator or captain

POST /v1/seat/events/{id}/reply — Answer an escalation from the seat

The reply lands in the escalating conversation as his own message and settles that run.

Bearer: operator or captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "text": "On it — the build is green."
}

GET /v1/fleet/seats/{paneId}/events — Long-poll a fleet seat's mailbox

A DM or room turn queued for a bound fleet seat (ADR 0161). Polling is what binds the mailbox: clankie mcp --seat asks again the moment a poll returns and pushes each event into the session as a channel notification. Operator bearer only; a Discord bridge bearer is 403. wait is capped at 30000 ms. unknown_seat (404) is the pane before herdr has classified the harness; the bridge retries.

Bearer: operator or captain

Discord

GET /v1/discord/user-session/opt-in — Current user-session opt-in

Bearer: captain or operator

POST /v1/discord/stream-watch — Bridge report of shares and optional stills

Bearer: captain

GET /v1/discord/readiness — Discord captain readiness

Requires a Discord text or voice bridge bearer.

Bearer: discord text or discord voice

POST /v1/discord/voice-briefing — Compose the realtime voice briefing

Voice-bridge bearer only. Request carries ids; persona is owner-authored.

Bearer: discord voice

Request body (required JSON)

{
  "schemaVersion": 1,
  "guildId": "123456789012345678",
  "channelId": "123456789012345679",
  "consentedUserIds": [
    "123456789012345680"
  ]
}

POST /v1/discord/presence-session-events — Apply a Discord presence phase event

Bearer: discord text or discord voice

Request body (required JSON)

A JSON object.

GET /v1/discord/presence-sessions — Full presence session records

Bearer: captain

GET /v1/discord/voice-history — Completed voice stays

Bearer: captain

POST /v1/discord/presence-actions — Execute a policy-gated Discord action

Needs a live-session claim in headers: x-clankie-discord-presence-session, x-clankie-discord-presence-phase, x-clankie-discord-presence-revision.

Bearer: discord text or discord voice

Request body (required JSON)

{
  "schemaVersion": 1,
  "idempotencyKey": "yaak-typing-1",
  "action": "discord.presence.typing_start",
  "identity": {
    "presenceSessionId": "replace-me",
    "correlationId": "yaak-1",
    "profileHash": "unversioned",
    "characterId": "clankie",
    "credentialRef": "discord_bot",
    "transportKind": "bot"
  },
  "payload": {
    "kind": "typing_start",
    "channelId": "123456789012345679"
  }
}

Memory

GET /v1/memory — Browse every captain episode and Discord person fact

Bearer: operator

POST /v1/memory/discord-people/proposals — Upsert a Discord person fact

Bearer: discord text or discord voice

Request body (required JSON)

{
  "schemaVersion": 1,
  "proposalId": "yaak-proposal-1",
  "fact": {
    "schemaVersion": 1,
    "factId": "yaak-fact-1",
    "subject": {
      "guildId": "123456789012345678",
      "userId": "123456789012345680"
    },
    "kind": "person-fact",
    "body": "Prefers short replies.",
    "visibility": {
      "scope": "guild"
    },
    "provenance": {
      "correlationId": "yaak-1",
      "sourceEventId": "yaak-src-1",
      "sourceSurface": "discord_text",
      "rawTranscript": false
    },
    "confidence": 0.8,
    "createdAt": "2026-08-15T20:00:00.000Z",
    "updatedAt": "2026-08-15T20:00:00.000Z"
  }
}

GET /v1/memory/discord-people/{guildId}/{userId} — Recall Discord person facts

Bearer: discord text or discord voice

DELETE /v1/memory/discord-people/{guildId}/{userId} — Delete every fact for a Discord person

Bearer: operator

GET /v1/memory/discord-people/{guildId}/{userId}/export — Operator export of a Discord person

Bearer: operator

PATCH /v1/memory/discord-people/{guildId}/{userId}/{factId} — Edit one Discord person fact without changing its identity or provenance

Bearer: operator

Request body (required JSON)

{
  "body": "Prefers concise replies.",
  "confidence": 0.9
}

DELETE /v1/memory/discord-people/{guildId}/{userId}/{factId} — Forget one Discord person fact

Bearer: operator

GET /v1/memory/captain-episodes — Recall episodes for a lane

Without query, the bounded recent card. With one, on-demand search over everything retained, filtered by what that lane may see. Both branches answer with a rendered card and never with episode records, so no caller reads another memory's provenance ids.

Bearer: captain

POST /v1/memory/captain-episodes — Record a self-authored episode

Recording only ever adds. An id the store already holds is a conflict, not an update; a byte-identical retry returns the original. Editing an existing note goes through PATCH. A Discord bearer may only write the lane it serves (discord_text writes discord_presence, discord_voice writes its own).

Bearer: captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "episodeId": "yaak-ep-1",
  "lane": "operator",
  "targetId": "self",
  "summary": "Tried the HTTP API from Yaak.",
  "visibility": "operator_private",
  "retained": false,
  "provenance": {
    "characterId": "clankie",
    "sessionId": "captain",
    "selfAuthored": true,
    "rawTranscript": false
  },
  "occurredAt": "2026-08-15T20:00:00.000Z"
}

PATCH /v1/memory/captain-episodes/{lane}/{episodeId} — Edit one episode's note, visibility, or retention

Bearer: operator

Request body (required JSON)

{
  "summary": "Corrected note about what happened.",
  "visibility": "operator_private",
  "retained": true
}

DELETE /v1/memory/captain-episodes/{lane}/{episodeId} — Forget one captain episode

Bearer: operator

Embodiment

POST /v1/embodiment/intents — Ask to start or stop play

Bearer: captain

Request body (required JSON)

start

{
  "kind": "start",
  "schemaVersion": 1,
  "intentId": "yaak-start-1",
  "originLane": "operator",
  "requestedBy": "local-operator",
  "requestedAt": "2026-08-15T20:00:00.000Z",
  "environmentId": "pokemon-firered",
  "budget": {}
}

stop

{
  "kind": "stop",
  "schemaVersion": 1,
  "intentId": "yaak-stop-1",
  "originLane": "operator",
  "requestedBy": "local-operator",
  "requestedAt": "2026-08-15T20:00:00.000Z",
  "sessionId": "replace-me"
}

GET /v1/embodiment/sessions/live — Live play session

Captain or operator.

Bearer: operator or captain

POST /v1/embodiment/sessions/live/stop — Operator kill-switch (ordinary stop intent)

Bearer: operator

GET /v1/embodiment/sessions/live/activity — Present-tense self-observation

Bearer: operator or captain

GET /v1/embodiment/sessions/live/still — One still of the live play screen

Read-only glance. PNG as base64. No controller.

Bearer: operator or captain

GET /v1/embodiment/sessions/live/story — Bounded story of this playthrough

Journal projection — objective, maps, last notable moments. Not the raw log.

Bearer: operator or captain

GET /v1/embodiment/sessions/{id} — One embodiment session

Bearer: captain

Browser

GET /v1/browser/tools — Live browser tool catalog

Bearer: operator or captain

POST /v1/browser/call — Call a browser tool

Calls one raw agent-browser MCP tool from the live catalog.

Bearer: operator or captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "tool": "agent_browser_snapshot",
  "arguments": {}
}

Media

POST /v1/media/images — Generate or edit an image

Bearer: operator or captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "prompt": "a small robot sitting at a terminal",
  "aspectRatio": "1:1"
}

POST /v1/media/videos — Start or resume a video render

Bearer: operator or captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "prompt": "a small robot waving",
  "durationSeconds": 6
}

Pairing

POST /v1/pairing/offer — Mint a one-time pairing offer

The offer secret appears once in the response. Do not log it.

Bearer: operator

POST /v1/pairing/redeem — Redeem an offer into a pending device

Unauthenticated. The offer secret or typed code is the capability.

Bearer: none

Request body (required JSON)

{
  "code": "123-456",
  "device": {
    "name": "Yaak",
    "platform": "macos"
  }
}

POST /v1/pairing/complete — Activate a pending device

Bearer: none

Request body (required JSON)

{
  "completionToken": "replace-me",
  "acceptedGrants": {
    "chat": true,
    "steer": true,
    "terminalObserve": true,
    "terminalControl": false
  }
}

Devices

GET /v1/devices — List paired devices

Secret-free rows. push carries the device's last delivery state — { registrationId, sequence, enabled } — so the listing is truthful about a device that turned notifications off or whose registration the gateway invalidated. The APNs token and delivery key are never here (ADR 0159).

Bearer: operator

POST /v1/devices/{id}/revoke — Revoke a device

Bearer: operator

GET /v1/devices/self — Device reads its own registration

Bearer: device

POST /v1/devices/self/push — Device records or clears its push delivery reference

Body is { registrationId, sequence, enabled }. The host stores only the reference, its version and whether delivery is on — never the APNs token or the delivery key, which the app registers with the gateway directly (ADR 0159). Disabling records that state at its version rather than forgetting it, so ordering survives it.

An older sequence is 409 stale_push_registration. The same sequence is accepted only when it restates what was already recorded: a different registrationId, or the same one with enabled flipped, is 409 conflicting_push_registration. That is also what refuses a re-enable at the version a gateway invalidation was recorded against.

Bearer: device

POST /v1/devices/self/session/refresh — Renew a device session token

Bearer: device