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 service contract on Clankie’s host. The public network surface exposes a bounded subset through api.clankie.bot; the host still decides every device grant. Hosted account and billing endpoints are separate contracts.

Bearers

Routes

Health

GET /health — Public liveness

Optional Herdr, gateway, host-power, runtime identity and runtimeHealth findings do not change service liveness. runtimeHealth contains fixed CPU percentage, health latency, duration, reason/alarm/delivery enums and incident timestamps; no conversation content. power says whether this host may sleep and when it last did (@clankie/protocol/host-power; docs/always-on.md). When available, runtime exposes only this service boot's pid, commit, root and instanceId; update transaction details are omitted.

Bearer: none

Operator

GET /v1/operator/http-settings — Read the shared core and relay browser-origin allowlist

Requires an owner operator or current terminal-control device. CORS grants no authentication.

Bearer: none

POST /v1/operator/http-settings — Replace the exact browser-origin allowlist

Empty disables browser access. No wildcard, credentials, paths, trailing slash or opaque origin; no restart required.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/machine-joins/approve — Owner approves a pending host, ceiling and directory subset

Strict {code, accessLevel, directories}. CODE is the 43-character base64url approval secret copied from the joining host. Operator bearer or a current paired device with Take Control; authority rechecked before persistence. This route stays behind device-envelope encryption at the gateway.

Bearer: operator or device

Request body (required JSON)

A JSON object.

PATCH /v1/machines/{id}/access — Set the owner-chosen machine capability ceiling

Cumulative portal, workers, shell and screen levels. Existing local installs retain screen; ungranted remote machines start at portal. Current enforcement is service-preference for ordinary local/SSH and joined-host for registered outbound receivers. A verified native macOS envelope reports os-sandbox, accessCeiling and approvedDirectories in machine inventory. Raising beyond that ceiling refuses until the owner removes the envelope and launches a new service. Actor and directory grants remain independent.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/checkouts — Inspect enrolled local owner checkouts against cached origin/main

Bearer: operator

POST /v1/checkouts/sync — Fetch and safely fast-forward enrolled owner main checkouts

Preserves local commits and overlapping edits; blocked results name files and modification age. Never stashes or resets.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/checkouts/reclaim-caches — Reclaim verified caches in clean inactive enrolled linked worktrees

Manual only. Six-hour retention; complete native process cwd and pane inventories. Removes ignored package-manager node_modules and CACHEDIR.TAG Rust target, at most 32 per sweep. Keeps commits, source edits and logs; unknown observations refuse.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/checkouts/prune — Preserve evidence and remove one landed clean inactive enrolled worktree

Landed means merged, on main by content (git cherry), or a recorded safe_to_drop decision for its exact HEAD, whose commits stay under refs/clankie/dropped-worktrees/. Fetches main, copies ignored .local evidence, rechecks cwd and foreground cwd of local panes, and uses git worktree remove without force. Deletes only merged branches. Main and runtime trees stay protected.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/checkouts/decide — Record a judgment of one linked worktree's unlanded work

Records worth_landing or safe_to_drop with a one-line reason for the worktree's current HEAD. Doctor and tidy show it; a new commit invalidates it. Never removes anything.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/integrate — Compose, gate and land an ordered approved commit batch

Source-checkout service only. Run returns a durable request receipt immediately; poll status. Compatible requests waiting during a gate share batches of at most three. Conflicting members roll back; failed shared gates retry members individually, alternating with waiting work. Waiting and active isolating requests can be cancelled before landing; a gate containing a withdrawn input cannot land, even if green. Status exposes progress.queuePosition, progress.isolationChain and a conditional progress.estimatedCompletionAt based on recent completed gates (null without measurements). Status without an id returns running batches, waiting requests, the last result and interrupted work. Independent clones and detached core/app sibling worktrees install real packages and run pnpm check with private home, state, credentials and caches. Only the recorded zero-exit exact HEAD may land. Core pushes first; app failure retains partial core-landed/app-pending evidence. Revert selects a passed batch via restore and creates a new commit restoring its tree. No force push or automatic push retry. Each active attempt automatically holds runtime updates until its safe point, bounded at 60 minutes. Updates wait on these holds even past a deferred dueAt; update status names each integrationBatchId. Waiting and accepted deploys fence new attempts. Interrupted newly accepted requests recover once with the same approved commits and a lead notice. Recovery checks remote main before pushing and records an already-present candidate without another send. Historical requests without recovery metadata and second interruptions require review. Deploy holds protect the running service from runtime updates and never gate landing. A hold names its minutes (1-60) and lifts on its own at expiresAt with an expire receipt; the runtime canary's own holds end with their canary. Releases and expiries return receipts naming the holder, actor and reason. Only the authenticated operator can invoke this route.

Bearer: operator

Request body (required JSON)

A JSON value.

GET /v1/runtime-update — Read runtime-update status and current deploy holds

Bearer: operator

POST /v1/runtime-update — Admit a local pinned-runtime deployment after the deploy-hold check

Bearer: operator

Request body (optional JSON)

A JSON object.

POST /v1/runtime-update/cutover — Confirm an idle scheduled release cutover after staging

Only the exact installing scheduled operation and running boot may act. Rechecks enabled and idle state. Waiting retains staging without stopping services. Ready closes turn admission and begins idle shutdown before the helper stops services and switches current. Uncertainty authorizes no stop.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/model-keys — List supported providers, models, stored-key status and captain selection

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. Shares the CLI model catalog and config. Returns no credentials or endpoint headers. Cache-Control no-store.

Bearer: operator or device

GET /v1/model-keys/subscriptions — List providers signed in through an account (OAuth or subscription) instead of an API key

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. Returns provider ids and names only; no tokens, expiry or account metadata. A separate read so clients parsing the strict model catalog never meet a new field. Cache-Control no-store.

Bearer: operator or device

GET /v1/model-keys/subscriptions/methods — List currently supported provider subscription sign-in methods

Bearer: operator or device

POST /v1/model-keys/subscriptions/start — Start a provider sign-in for the authenticated initiating principal

Reuses console sign-in helpers. Poll status for the URL and optional code, then open it in the initiating client's browser. Browser callbacks reach this Mac; phones use the device method. Credentials and the selected catalog model are committed together after a fresh authority check. Claude subscription login remains unsupported. No-store; no raw provider errors.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/model-keys/subscriptions/status — Read the initiating principal's sign-in interaction

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/model-keys/subscriptions/cancel — Cancel a pending sign-in; an admitted credential write finishes as committing

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/model-keys/options — List providers usable without key entry and the running model's reasoning effort

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. Returns provider ids and effort levels only; no credentials. A separate read so clients parsing the strict model catalog never meet a new field. Cache-Control no-store.

Bearer: operator or device

POST /v1/model-keys/effort — Set or clear the running model's reasoning effort for the next turn

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. Writes the same config as clankie effort set; null returns the model to its default. An effort the model does not accept, or no running model, is unsupported_model. Cache-Control no-store.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/model-keys/set — Store or replace a write-only provider API key

On a self-hosted Mac, device key entry returns forbidden when shared Clankie readiness is true. Operator key management and hosted behavior remain unchanged. The write rechecks readiness and authority. Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. No key, provider error text, or generated text is returned or logged. Cache-Control no-store. Validation uses a fixed prompt, 16 output tokens, no retries and a 15-second deadline; the provider may bill this request. Set does not validate implicitly.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/model-keys/validate — Validate the stored key with a bounded provider call

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. No key, provider error text, or generated text is returned or logged. Cache-Control no-store. Validation uses a fixed prompt, 16 output tokens, no retries and a 15-second deadline; the provider may bill this request. Set does not validate implicitly.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/model-keys/select — Select the captain model for the next turn

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. No key, provider error text, or generated text is returned or logged. Cache-Control no-store. Validation uses a fixed prompt, 16 output tokens, no retries and a 15-second deadline; the provider may bill this request. Set does not validate implicitly.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/model-keys/remove — Remove a stored API key without removing OAuth or environment fallback

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. No key, provider error text, or generated text is returned or logged. Cache-Control no-store. Validation uses a fixed prompt, 16 output tokens, no retries and a 15-second deadline; the provider may bill this request. Set does not validate implicitly.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/accounts/codex — List discovered local Codex identities and their homes

Owner-authorized. The same identity-keyed discovery as worker accounts and usage. Native account/read uses refreshToken:false; identity, plan and usage only. Multiple homes signed into one identity share one account. Missing or stale usage is unknown.

Bearer: operator or device

POST /v1/accounts/codex — Register or remove an owner's local Codex home

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/accounts — Read the body-owned GitHub, Linear and Google account catalog

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. Includes service purpose, permission disclosure, account identity, granted scopes, recovery status and selected Drive file IDs. An unconfigured Google row needs operator OAuth client setup; it does not request a customer credential.

Bearer: operator or device

POST /v1/accounts/github/start — Start a GitHub device flow; return the user code and verification URL

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. The device code stays on the body. Unconfigured without a GitHub OAuth client ID.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/github/poll — Poll a GitHub device flow; returns pending, connected or a closed error

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. Polls faster than GitHub's interval are answered by the body without calling GitHub.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/linear/start — Start registered Linear app OAuth with S256 PKCE; return the authorize URL

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. The PKCE verifier stays on the body. Tokens use the separate linear-api broker entry and GraphQL tracker, never MCP. Unconfigured without a redirect URI.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/linear/complete — Hand back Linear's redirect code; the body exchanges it with its verifier

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. state is single use.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/linear/app — Connect a workspace-owned Linear app for worker names and portraits

Verifies an app actor and workspace before replacing the Linear credential. Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. Client credentials and tokens stay in the broker and are never returned or logged. Cache-Control no-store. Enable client credentials tokens on the workspace's Linear OAuth application.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/google/start — Start body-owned Google consent with state and S256 PKCE

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. The body retains the verifier and keeps all client secrets and tokens in its broker. Cache-Control no-store. Gmail requests gmail.readonly plus openid email. Calendar requests calendar.calendarlist.readonly and calendar.events.readonly plus openid email. Drive requests only drive.file and opens Google Picker with prompt consent, trigger_onepick true and include_granted_scopes false. Google's selected-file grant permits editing; Clankie's implemented tools only read selected files. All flows request offline access. Client setup and browser consent are required.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/accounts/google/complete — Exchange the one-time Google code on the tenant body

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. State is single use, bound to this body's pending provider, OAuth application and expiry. The body verifies provider identity and granted scopes before storing credentials; no tokens or provider errors escape. Gmail and Calendar accept provider, state and code only. Drive also requires a nonempty unique pickedFileIds array, validated from Google Picker's picked_file_ids callback. These IDs bound the files the implemented Drive read tools can access. Cache-Control no-store. Authorization codes belong in the JSON body, never API request URLs or logs.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/accounts/google/check — Refresh and verify the selected Google account's authorized access

Owner operator bearer or active device with terminalControl only. Public gateway calls require the encrypted envelope. The body refreshes the selected grant under the credential-store lock and verifies its identity, scopes and disconnect epoch. Returns catalog metadata and last-check status without exposing credentials. Invalid grants require renewed consent; provider outages do not imply revocation. Cache-Control no-store.

Bearer: operator or device

Request body (required JSON)

A JSON value.

POST /v1/accounts/disconnect — Disconnect locally and report actual provider revocation

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Never returns or logs a token or provider error text. Cache-Control no-store. revoked is false when the provider could not confirm revocation; local access is disabled either way and manageUrl names where to review the grant. Disconnecting any Google provider disables all three Google connections on this body. Its broker may retain a refresh credential solely for bounded revocation retries; catalog revocationPending remains true until Google confirms revocation. Hosted GitHub disconnect never uses a developer app secret and reports revoked false. Owner-run self-hosted GitHub revocation deletes only the stored token, never an app grant.

Bearer: operator or device

Request body (required JSON)

A JSON object.

POST /v1/accounts/email/connect — Choose his Clankie mailbox in one step and return the email row

Owner operator bearer or active device with terminalControl only (ADR 0232). Public gateway calls require the encrypted envelope. Cache-Control no-store (ADR 0242). Asks Clankie's mail service first; only when it answers this install's Clankie account with his address does settings.email.provider become clankie, with that address as the from-address. A stored IMAP password is kept, so choosing IMAP again needs no new sign-in. account_required: not signed in to a Clankie account, or the service refused it (clankie login); unavailable: the service could not be reached; unconfigured: this install has no Clankie mail service. Settings are unchanged then.

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/connections — Inspect execution runtimes and verified Linear identity

Bearer: operator

GET /v1/runtime-connections — Inspect the default fleet and named execution connections

Bearer: operator

POST /v1/runtime-connections — Connect a Herdr runtime or configure owner execution policy

Resolves an explicit session or socket and pins that endpoint to the ID. Reconnection cannot retarget an existing ID. action=workspaces replaces additional repository/directory approvals for a named or default runtime; it never starts or stops workers. action=capacity sets one runtime limit; Unset limits default to 16; null clears a limit to unlimited; zero pauses new admission.

Bearer: operator

Request body (required JSON)

A JSON object.

DELETE /v1/runtime-connections/{id} — Disable a named execution connection while preserving workers and route identity

Bearer: operator

POST /v1/tracker/import/linear — Mirror a Linear project into a named scratch built-in tracker

Read-only on the broker-connected Clankie Linear app. Every collection is paginated, including archived issues. Imports provider IDs and VUH keys, comments/replies, history, labels, relations, milestones, documents, updates and team cycles. Uploads enter the evidence store with rewritten links. Shares the background request budget. Scratch stores live under tracker-imports, separate from the live tracker. Writes import-report.json and returns counts, skips, actor mappings and created/updated/unchanged totals. Does not switch the active backend. Multi-team mappings are refused.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/tracker/mirror/linear — Enable, disable or inspect a scratch import's Linear webhook mirror

Owner-enabled only; nothing mirrors by default. Enabling requires a scratch store imported from the named project. Accepted signed Linear webhooks for that project then apply through the import mapper once per Linear event id, attributed to the original actor. The mirror refuses built-in writes until cutover. Drift (an event naming an unknown record) triggers a scoped re-read through the connected account within the background request budget and is reported. Status returns counters, the applied event count and drift reports.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/tracker/cutover/linear — Cut a World project over from Linear to the built-in tracker, or switch it back

Mirror 3 (VUH-1987). A dry run reads only (Linear included) and returns the plan: per-type counts against a fresh read-only Linear capture, the mirror's state, the store, binding and convention changes with backup paths, refusals and the switch-back command. Without dryRun the plan is applied (mirror disabled, scratch import promoted to the live store, trackerProjectId bound, convention switched to builtin) or refused with HTTP 409 and nothing changed. switchBack restores the exact pre-cutover convention, binding and store and keeps the pilot store.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/work — Read and write work items in the repo's own tracking convention

One contract over Linear, GitHub issues, the repo's own Markdown directory, or .clankie/work/ (ADR 0191). action is repos, discover, init, list, show, project, create, update, attach, write or write_receipt. The two narrow owner operations take request {repoId,itemId,requestId,command}; receipt reads omit command. The command assigns work-metadata owner, adds/removes a role label or appends a blocker. Their applied/refused/uncertain receipt always carries the UUID; repeated IDs and receipt reads never replay a write. A path names and registers a local repo; registered repos are readable from paired devices through the work_repos, work_items and work_project operator ops. work_items statusVersion=2 opts into backlog and native milestone metadata; older requests receive backlog as todo. project reads planned milestones, shipped v* tags/published versions and Linear initiative goals. init accepts releaseSource (tags, milestones, both; default both) and releaseLane (default repository). Unavailable facts are explicit; store builds are not inferred. list takes optional status, owner and label (case-insensitive) filters; items carry the backend's labels (ADR 0208).

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/linear/routes — Inspect configured Linear project lead chats

Bearer: operator

PUT /v1/linear/routes — Replace Linear project destinations with existing ordinary global chats

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/linear/deliveries — Inspect offered Linear wake batches, destinations and target consumption receipts

Offered batches may have failed before delivery. receivedAt is set only by the target chat confirming its original wake; native transport ACKs alone do not mark Linear notifications read. Recoveries list missing-receiver holds, pending event IDs and durable per-event rerouted or already_handled resolutions to current lead destinations. Uncertain native takes remain pinned to their original recipient.

Bearer: operator

GET /v1/linear/target — Inspect the ordinary chat selected for Linear activity

Bearer: operator

PUT /v1/linear/target — Select an existing ordinary global chat without restarting

Sets linearWebhook.wakeConversationId, default global-default. The target must be an existing ordinary global chat; its attached native operator seat may drive it. Changing the target applies to new activity without moving or replaying history. Selecting a target grants no additional authority.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/auto/rounds — Read the Auto round record, newest first

Each Auto round's measured velocity per project (ADR 0270) and whether its wake was delivered. Closures since the last milestone split owner-facing, tooling, unlinked and unclassified; started issues (cap null until a WIP cap exists); churn by bucket; per-day facts for the window and the last seven local days. Any part the service could not measure is {state:"unknown", reason}, never zero. A round whose wake never settled has a null delivery. Reads the service-local record only; no tracker or git calls.

Bearer: operator

GET /v1/linear/request-budget — Read rolling provider request usage and background read throttling

Counts actual HTTP attempts across MCP and the API tracker per workspace and actor. The default 5000/hour cap reserves one request; provider remaining/reset headers can lower available headroom. At 50% a native runtime warning is emitted once until usage recovers; at 80% background reads share a one-minute minimum interval. Writes and webhook context retain priority within the hard cap. This diagnostic makes no provider calls.

Bearer: operator

GET /v1/linear/wake — Inspect actor and activity wake rules

Live rules apply to new signed activity without replay. The follow switch still gates wakes. Relayed GET/POST retain the original device authority.

Bearer: operator or device

POST /v1/linear/wake — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

PUT /v1/linear/wake — Save validated settings with revision fencing

PUT is the local compatibility alias; devices use POST. The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/linear/follow — Inspect following and webhook readiness

Following requires the configured signed webhook. Missing URL or secret refuses enablement. Passive activity remains visible without waking.

Bearer: operator or device

POST /v1/linear/follow — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

PUT /v1/linear/follow — Save validated settings with revision fencing

PUT is the local compatibility alias; devices use POST. The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/worker-grants/ — List worker grant records without bearer tokens

Bearer: operator

POST /v1/worker-grants/ — Issue a scoped grant for one verified connected account

Work ID is provenance. Exact top-level argument restrictions enforce resource boundaries; omitted arguments remain unrestricted. A fleet grant binds access to an authenticated fleet link until revoked; a manual grant requires private bearer delivery.

Bearer: operator

Request body (required JSON)

A JSON object.

DELETE /v1/worker-grants/{id} — Durably revoke one worker grant and close its sessions

Bearer: operator

GET /v1/worker-grants/linear/account — Inspect disconnected, unverified or verified Linear account identity

Bearer: operator

POST /v1/worker-grants/linear/account — Verify the stored Linear account's provider user and workspace

Verifies API keys via GraphQL and OAuth via Linear's official MCP identity tools. Credentials are never migrated automatically.

Bearer: operator

POST /v1/hosted/operator — Dispatch as an account-paired hosted operator device

Encrypted gateway carrier required remotely. Checks active device session, server-recorded operator pairing purpose and Take Control grant. No operator bearer is exported. The shared hosted-device allowlist permits chat, fleet, terminal, model, keys, persona and connections. Restart, reset and deprovision require account authority, including through the legacy device relay. The inner route keeps its own validation. Revocation is rechecked before returning a parked page.

Bearer: device

Request body (required JSON)

A JSON object.

POST /v1/runtime-connections/{id}/prepare — Prepare Clankie's own harness setup on an existing machine

Resolves policy from the verified service-local source workspace and checks the target's current link independently. Lead setup requires an already-linked target. Owner policy or a newly supplied source script requires the caller's ownerApproved consent claim. The service records that claim without verifying human confirmation. expectedMachineRevision pins the exact registered target shown to the caller; omission claims the alias's current target. This retains operator authority and never restarts or steers existing lanes.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/operator/work-tracker — Read the new-project default or one project's saved tracker

Bearer: operator or device

POST /v1/operator/work-tracker — Read, preview or set the new-project default or a project's work tracker

Owner-only API shared by every surface. Built-in and repo files need no account; Linear and GitHub use existing connected accounts. Project changes require a matching preview revision and confirmRetainItems. Existing items stay in their old tracker; nothing migrates or is deleted. Discord forum remains a future built-in view (VUH-2531).

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/operator/fleet-settings — Read fleet size, model mode and owner working preferences

Closure, machineSetup, commit and push default to lead; official releases default to owner, verification to change_run_read, reporting to Short and plain. workingPreferences=true advertises the five new controls; old responses may omit them. Existing owner or Take Control device authority is required; preferences confer no credentials or new access.

Bearer: operator or device

POST /v1/operator/fleet-settings — Update fleet budget and working preferences with revision fencing

Omitted leaves retain their value. A null autonomy leaf restores its global default. Release mode and rule are replaced together. Retired size, models, verification, reportingStyle and hire.effort edits are rejected. Saved values remain in the read-only includeWorkPolicy=true receipt.

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/operator/fleet-settings/hire — Read the fleet's hire defaults (harness and model; legacy effort read-only)

An omitted field is "no preference"; Clankie chooses per hire. The SHA-256 revision covers the whole stored hire profile, so an account, subagent, delegation or placement change also fences writes. Owner or Take Control device authority (FleetHireDefaultsSnapshotSchema).

Bearer: operator or device

POST /v1/operator/fleet-settings/hire — Set or clear fleet hire defaults

Accepts schemaVersion=1, expectedRevision and changes {harness?, model?}. The value auto clears a field; effort accepts only auto to clear a retired saved value. Any field patch removes legacy global effort while preserving it in the retirement receipt and retaining other profile fields (UpdateFleetHireDefaultsSchema).

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/worker-accounts — Read one machine's worker accounts and verified Pi profile

Discovered identity-keyed accounts and their homes, sign-in, email, plan, usage headroom, re-sign notices, verified Pi model references, holds and whether Clankie would hire now (MachineWorkerAccountsSchema). Duplicate homes share one account; preferences remain with the identity after a home re-signs. Omit fleet for this machine; fleet names a runtime connection, the only query accepted. Owner or Take Control device authority.

Bearer: operator or device

GET /v1/worker-accounts/holds — Read held worker accounts and current revision

Holding prevents automatic selection; naming the account explicitly still permits a hire. Hold and release update one account and return all current holds.

Bearer: operator or device

POST /v1/worker-accounts/holds — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/usage — Read account usage, optional native fleet context spend and where the next hires go

Each registered Claude profile and Codex account with identity, plan, headroom and its usage windows (percent used, length, reset, source and observation age), read through each harness's own CLI and shared for a minute across surfaces; refresh=1 reads again now. allocation.accounts ranks each eligible account per harness by spare capacity per day (planWeight, tier, remaining, sparePerDay, window, burnPerDay, resetsAt, runsOut, rank, reason); allocation.recommendations names the next automatic hire per harness with its reason (ADR 0261). settings carries the overlay and run-out warning settings with their revision. Never credentials (UsageReportSchema). fleet=1 adds an on-demand local native-transcript ledger in fleet, cached for one minute independently of account polling. Each session and UTC day reports modelCalls, contextTokens, medianContextTokens, aboveBudgetContextTokens, aboveBudgetTokenShare, above400KContextTokens, compactions and foregroundSleepCalls. Claude input includes cache reads and writes; Codex uses token_count input (cached input is already included). Native message/response IDs deduplicate streaming records and retained copies; older Codex responses use repeated cumulative snapshot identity. Children have separate subagent rows. Role attribution comes from the native census, hire journal and lead relaunch journal; unknown historical roles use the 300K worker review budget and are labeled unknown. Lead budget is 250K. Above-budget share is the fraction of context tokens in calls strictly above that seat budget. Warnings preserve unreadable/malformed sources and unknown attribution. These are raw token volumes; vendor account windows remain independent. days defaults to 7 (1..366); since and days are mutually exclusive; until defaults to now, with a positive interval no longer than 366 days. Ordinary meter reads never scan transcripts.

Bearer: operator or device

GET /v1/usage/settings — Read the usage overlay and run-out warning settings

display.overlay, allocation.runOutWarning and allocation.runOutWarningHours with their SHA-256 revision (UsageSettingsSnapshotSchema).

Bearer: operator or device

POST /v1/usage/settings — Save usage display and run-out warning settings with revision fencing

expectedRevision from GET is required, with display.overlay and/or allocation.runOutWarning (boolean) and allocation.runOutWarningHours (0-168): the lead is woken once per window reset when an account's weekly limit is on pace to run out at least that many hours before it resets (UpdateUsageSettingsSchema).

Bearer: operator or device

GET /v1/operator/fleet-settings/context — Resolve current project policy and already-linked setup target

Verifies a local source directory and Git worktree separately from the registered target machine. Returns a nonsecret targetRevision hashing the resolved execution descriptor, including transport and session, so consent can be pinned across requests. Machine aliases hash their registration set rather than selecting an arbitrary runtime. Invalid or ambiguous project evidence fails closed. This filesystem route is excluded from hosted-device forwarding.

Bearer: operator or device

GET /v1/operator/reviews — List landing review candidates, newest first

The standing review gate's candidates (ADR 0287) with status, author, reviewer, verdict and any waiver. At most 500. An operator bearer reads and waives but never records a verdict.

Bearer: operator

GET /v1/operator/reviews/{id} — Read one landing review candidate

With patch=true, also the stored patch bytes, base64.

Bearer: operator

GET /v1/operator/reviews/landing — Ask whether one exact patch may land

The landing gate's question (ADR 0287). The service maps the checkout directory to its project. landable is true when the project names no reviewer, the change is empty, or the patch-id is approved or waived. Otherwise status is not_submitted, awaiting_review or changes. clankie review status and pnpm check:landing ask this; the gate exits 3 while landable is false.

Bearer: operator

POST /v1/operator/reviews/waivers — Land one exact patch without its project's review

Owner only. Records the owner, the reason and the time on the candidate for exactly this patch-id, and the landing gate then lets that patch land. The service recomputes the patch-id from the bytes and refuses a mismatch. The lead's waive_review tool does the same on the operator lane. Rare by design.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/operator/projects/update — Update project policy while preserving independent inheritance

Each autonomy.fleet leaf overrides its global default independently; null clears only that override and omission retains it. Release mode and rule are one atomic leaf. Responses omit autonomy fields unless includeAutonomy=true; workingPreferences=true then advertises support for the new controls. The expectedRevision fences full project settings even for legacy projections. linearProjectBinding names a connected Linear project by exact UUID, independently of the built-in trackerProjectId. It never changes a saved tracker backend; null clears only the Linear reference. The autonomy-aware view advertises linearProjectBindings=true. review names the standing landing reviewer (ADR 0287); it appears only with includeReview=true.

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/operator/projects — Read owner project settings and their current revision

Legacy responses omit autonomy and work-policy fields. includeAutonomy=true adds autonomy overrides and defaults. includeWorkPolicy=true adds wipCap, ownerLoop, hiring, projectWorkPolicy=true and a read-only retiredWorkingPreferences receipt. includeAutoUpdates=true adds autoUpdates and projectAutoUpdates=true. includeReview=true adds each project's standing reviewer as review and projectReview=true. Revision always covers the full stored settings.

Bearer: operator or device

POST /v1/operator/projects/create — Create a reviewed project with one canonical local workspace

Owner only. Strict fields are projectId, name, workspacePath, expectedRevision, roles, workerCap, trackerRef, trackerSetup, productPaths, wipCap, ownerLoop, autoUpdates and hiring. The service supplies primary/local workspace identity and its platform. Nullable worker caps inherit; zero is preserved. Retired fleet preferences cannot be created. Optional trackerRef must name primary and .clankie/tracking.json, an existing valid canonical convention unless trackerSetup supplies reviewed work-init inputs for a missing convention. Tracker save precedes settings save; a partial failure can leave only the convention. No automatic retry, account choice, provider project/label creation, remote enrollment, assignments, hires or grants. Rechecks canonical directory/tracker identity, settings revision and owner authority before the existing SettingsStore rename. These asynchronous observations are not cross-process compare-and-swap or atomic authority/filesystem checks. This documents the source contract, not an installed CLI or running-service update.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/operator/projects/remove-workspace — Remove one exact owner-approved workspace registration

Preserves roles, grants and assignments. Refuses tracker-bound workspaces, stale revisions, changed owner authority and concurrent settings changes. Does not delete a directory.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/fleet/worker-tool-refresh — Refresh worker catalogs through their original native controllers

Without paneId, selects only seats led or hired by the default owner conversation and lists others as skipped-not-owned. Cross-conversation refresh requires explicit paneId and owner authentication. Preserves original threads, receipts and controller identity. Never starts a proof turn, restarts a harness or replays a report. Local Codex catalog-refreshed means its MCP catalog is connected and complete; next-turn model tools and new report delivery remain unverified. Have that same worker call clankie_tools and send one new message_clankie report to prove delivery. Busy requests defer under their original authority; unsupported controllers refuse explicitly.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/fleet/worker-tool-restart — Check admission for explicit same-thread worker restart

Explicit operator action. Requires saved results, settled report receipts, known ownership, no draft and a verified native exit controller. Rechecks the original occupant before exit and journals close/resume. Unknown exit or resume receipts remain held; inspect tidy history before retrying. Current local Codex lacks verified native exit and refuses before any close intent; successful automatic restart remains unsupported. Remote workers and Claude are unsupported.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/harness-refresh — Refresh existing native worker plugin links locally and on enabled fleet machines

Uses the native harness installer without enrolling new profiles, changing channel policy or restarting panes. The canonical source workspace selects current machineSetup policy; owner mode requires the caller's ownerApproved consent claim, and automatic lead refresh requires an already-linked target. The service records the claim without verifying human confirmation. Current operator authority, source context and each captured fleet destination are revalidated before refresh. Returns per-profile and per-fleet outcomes; ok is false for incomplete installation, missing source setup or unreachable machines.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/harness-plugin-version — Tell a running service which worker version the installer shipped

Updates display-only restart flags at the next admitted native client request. Client version reports confer no tool authority, and nothing is restarted.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/runtime-connections/{id}/harnesses — Inspect native harness registration on one registered remote fleet

Reports profile activation, service versus installed version, bridge, hooks and skill presence. Static registration never establishes live process membership or receiver proof.

Bearer: operator

GET /v1/runtime-connections/{id}/membership — Inspect host-observed project eligibility on one registered remote fleet

Reports bounded per-pane process, native session, hire and actual cwd observations. Host eligibility does not verify a bridge socket, native tool catalog or delivery. Rechecks the configured fleet, settings, hire, native observations and caller authority before returning.

Bearer: operator

GET /v1/operator/persona — Read owner-authored character and talkativeness

Full operators receive persona and image diagnostics. A Take Control device projection may read and change only chattiness and replyPolicy; its revision still fences the full persona. Images are service-host paths and changes require restart to apply.

Bearer: operator or device

POST /v1/operator/persona — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/operator/host-settings — Read keep-awake and automatic update preferences

Shared labels are HOST_SETTINGS_WORDING in protocol. keepAwakeSupported is false on hosted or non-Mac hosts. Managed hosting keeps autoUpdate enabled; it cannot be disabled. A saved preference does not grant deployment or restart authority.

Bearer: operator or device

POST /v1/operator/host-settings — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/operator/appearance — Read which bundled skin Clankie wears on the owner's surfaces

leadSkin is a client skin id; "pack" keeps the selected skin pack's own lead. The service validates only its form, and clients fall back to "pack" for an id they do not bundle.

Bearer: operator or device

POST /v1/operator/appearance — Choose Clankie's look with revision fencing

The expectedRevision from GET is required. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

GET /v1/operator/maximum-trust-mode — Read whether maximum trust mode is on

While on, every harness Clankie launches next starts without its own permission and command guardrails, through its native flag (Claude --dangerously-skip-permissions, Codex approval_policy=never with sandbox_mode=danger-full-access, Grok --permission-mode bypassPermissions). Running seats keep the mode they launched with. Separate from the autonomy dial.

Bearer: operator or device

POST /v1/operator/maximum-trust-mode — Turn maximum trust mode on or off

Owner-only. Applies to the next launches of the operator seat, hires and remote project leads.

Bearer: operator or device

Request body (required JSON)

A JSON object.

GET /v1/operator/runtime-health — Read runtime CPU and health alarm settings and metadata

Owner or Take Control device authority. Returns schemaVersion=1, a SHA-256 settings revision, settings, and the fixed RuntimeHealthObservation from packages/protocol/src/runtime-health.ts. Process CPU is wall-time-normalized process.cpuUsage; 100% is one fully busy core. No conversation content.

Bearer: operator or device

POST /v1/operator/runtime-health — Change runtime health alarm thresholds without restarting

Accepts schemaVersion=1, expectedRevision and a strict partial changes object. Defaults are enabled=true, cpuPercent=50, healthLatencyMs=1000, sustainedMs=300000, sampleIntervalMs=15000 and cooldownMs=1800000. Settings apply on the next sample. Native global-default delivery emits one alarm and one recovery with incident duration; it creates no service model turn. The schema and bounded ranges live in @clankie/protocol.

Bearer: operator or device

Request body (required JSON)

{
  "schemaVersion": 1,
  "expectedRevision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "changes": {
    "cpuPercent": 50,
    "healthLatencyMs": 1000,
    "sustainedMs": 300000
  }
}

GET /v1/operator/voice — Read stored and effective voice settings

Provider, model and public voice identifiers only; credentials remain in the broker. Device forwarding requires Take Control. Changes need the active Discord body restart to apply and do not contact providers or restart bodies.

Bearer: operator or device

POST /v1/operator/voice — Save validated settings with revision fencing

The expectedRevision from GET is required. Validation and current owner authority are checked before persistence. No automatic conflict retry.

Bearer: operator or device

Request body (required JSON)

A JSON value.

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

Without a connection ID, pending default-fleet settings apply on service restart. Named connections resolve their pinned endpoint and current health. No unavailable connection falls back to the default fleet.

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. Includes legacy human recognition and assistant generated wording (role: assistant, speakerId: clankie, itemId, optional playbackId/responseId, textSource, textComplete, audioStarted, playbackMs, outcome). Outcomes are played, interrupted, suppressed, failed, or truncated. Generated text may include an unheard ending after a cutoff; no raw audio or word-aligned audible transcript is retained.

Bearer: captain

POST /v1/remote-leads/{action} — Prepare, launch or revoke a Windows Claude project head

Owner-only management. Launch uses a stable requestId; repeated requests return the original journal without redispatch. Dispatched is a transport handoff, not native readiness. Unconfirmed launches need reconciliation. The separate process-bound delegation never authenticates owner routes. Restart recovery requires the original host-pinned process/session/chat. Private records contain token hashes only; explicit revoke survives restart.

Bearer: operator

Request body (required JSON)

A JSON value.

GET /v1/fleet/metrics — Read fixed-reason fleet proof and report counters

Operator-only, content-free counts since service start and five/sixty-minute rates. Proof terminal admissions/refusals, receipt observations, native retries and transport failures are separate. Bounded five-minute caller windows use claimedPane request labels, not authenticated identities. No PIDs, paths, argv or report bodies. Contract: FleetHealthMetricsSnapshotSchema in packages/protocol/src/fleet-health-metrics.ts.

Bearer: operator

GET /v1/fleet/lead-restart — Read the default lead seat's fresh-restart budget, last check and refused wait

Operator-only. The ADR 0271 budget (context tokens and session age), the latest known check since service start (context, session start, whether a restart is due), optional unknownCheck metadata if source or usage is unknown (the legacy optional check is then absent), and the refused wait: when it began, the latest refusal and a count per refusal reason, and when the owner was told. The wait lasts across service restarts until the seat relaunches or is no longer due. Contract: LeadRestartStatusSchema in packages/protocol/src/fleet-settings.ts.

Bearer: operator

GET /v1/fleet/seat-restarts — Read hired-seat restart checks, durable refusals and original receipts

Operator-only, no-store. Reports the default-on seatRestarts setting, 450K token budget, checks and refusal counts for each exact native session, and handoff/restart receipt IDs. Unknown native state refuses an exit. Contract: SeatRestartStatusSchema in packages/protocol/src/seat-restarts.ts.

Bearer: operator

POST /v1/fleet/seats/{paneId}/messages/health — Record a native worker's content-free receipt health

Requires the current admitted native session. This observation does not send or replay a report and does not grant tool authority. Unknown panes, changing native bindings and fields beyond the strict status are refused.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/fleet/efficiency — Inspect owned seats or record a worker review

show returns every seat led by the exact conversation, including linked fleets, with optional factual efficiency evidence. review records inspected scope, tracker status or substantive progress for one exact owned native session. A review can record a reassigned deliverable or ownedIssues explicitly reported live on that session or its native children; an empty list clears those claims. Explicit deliverables carry deliverableAssignedAt, which ordinary messages cannot refresh. It changes no tracker state, harness settings, native seat ownership or report receipts. Unknown telemetry is omitted, never treated as healthy. Flags are observations for the lead skill; they do not prescribe or perform worker actions. Every watch wake calls for reviewing all owned seats; periodic lead rounds default to 30 minutes and coalesce while a review turn is outstanding. Prompts carry bounded summaries; use show for full details and every-owned inspection. Original report acceptance or attempt remains progress after acknowledgment; acknowledgment creates no new progress. Context percentage is the latest native Codex model-input snapshot and may age between responses. Claude context/effort and OpenCode or remote telemetry remain unknown.

Bearer: operator

Request body (required JSON)

show

{
  "action": "show",
  "conversationId": "global-default"
}

review

{
  "action": "review",
  "conversationId": "global-default",
  "seatId": "worker-seat",
  "assignmentStatus": "active",
  "deliverable": "VUH-1662",
  "evidence": "Reviewed the assigned issue and current worker report."
}

POST /v1/fleet/tidy-worktrees — List merged, clean worktree cleanup candidates

Read-only listing from the exact canonical repository root and locally saved merge ref (origin/main by default); it never fetches refs or removes worktrees. Main, locked, prunable, dirty, unmerged and live-pane worktrees are excluded. Idle agents and shells also protect their directories. Unverified paths, unavailable or changing refs, and an incomplete or changing local pane inventory return outcome unavailable with no candidates. Candidate status does not prove ownership; the tidy skill verifies ownership, preserved results and fresh landing evidence before any separately authorized removal.

Bearer: operator

Request body (required JSON)

A JSON value.

GET /v1/fleet/tool-catalog-health — Read native catalog health for every current Claude and Codex seat

Includes the operator head. Reports from a previous occupant are never reused.

Bearer: operator

POST /v1/operator/projects/add-worktree-root — Enroll a repository-bound linked-worktree root

Owner only. Requires projectId, machineId, platform, path, repoPath and expectedRevision. The service observes canonical root/repository paths and Git common-directory identity, then rechecks native facts, authority and revision before saving. The repo must exactly match an approved workspace in the project. This confers no tool grant.

Bearer: operator

POST /v1/operator/projects/remove-worktree-root — Remove a linked-worktree root enrollment

Owner only. Requires projectId, rootId and expectedRevision. Rechecks authority and revision before persistence. Deletes no filesystem content.

Bearer: operator

GET /v1/games/extensions — Discover registered game extension lifecycles

Read-only local metadata and lifecycle health. Does not join a game, probe credentials or call a model. Ready does not prove live gameplay or media. Registration and removal are trusted in-process composition, not model-authored manifests.

Bearer: operator

GET /v1/minecraft — Read the current Minecraft body session

Operator-authenticated read of the approved offline Java body. Account material and raw endpoints are excluded. x-clankie-conversation-id selects an existing owning conversation.

Bearer: operator

POST /v1/minecraft — Join, choose a driver, act, inspect, pause, cancel or leave Minecraft

Joining starts the configured continuous play mind. Use driver to hand off to owner, mind or a chosen admitted worker; it quiesces prior motor work without transferring the conversation play lease. Direct act requires owner driver. Long work returns a handle. The shared play lease is retained until exact confirmed disconnect. Completion is distinct from server-verified effects.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/minecraft/host — Configure, start, administer or back up Clankie's own Minecraft server

Integration-owned on-demand Paper host and broker-backed playit claim. claim starts background agent preparation and returns preparing immediately; claim_status reads preparation progress and returns the official approval URL when pending and claim_complete polls once and stores an approved secret only in the broker. Tunnel claiming requires owner/admin authority. Hosting is off by default, idle-stops after at most 15 minutes, and has a maximum uptime watchdog. x-clankie-conversation-id selects an existing operator conversation. Typed administration has no op, raw RCON or secret arguments. Enrollment approval uses a previously verified Discord requester; operator arguments cannot select a Discord subject.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/minecraft/configuration — Read owner Minecraft profiles, destination allowlist and play settings

Offline host, port, version, username and explicit public destination grants. This operator configuration does not appear in model tools.

Bearer: operator

PUT /v1/minecraft/configuration — Replace offline Minecraft profiles, public destination grants and play settings

Owner-only settings write. DNS and SRV destinations are checked again before dial; model calls cannot supply raw host or authentication arguments.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/pairing/local/offer — Mint the same-UID Mac companion handoff through owner-private IPC

Self-hosted macOS only. The CLI uses the protected Unix socket, never unverified TCP. Local native transport and operator bearer are required. The five-minute offer is not published to the gateway or generic store. A new mint invalidates its predecessor. No-store; secrets never enter logs.

Bearer: operator

POST /v1/pairing/local/redeem — Redeem the owner-local handoff once over native loopback

Refuses browser pages, forwarded requests, the gateway and the LAN device doorway. Only a process whose running code satisfies an owner-trusted code requirement may redeem (VUH-2604); any other app is refused without consuming the offer and recorded as pairing.local_companion.refused. Reuses the active companion's durable device ID and grants on reinstall. Revoked identities never revive. Session uses the existing device signer and includes host, grants and loopback control/relay routes.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/pairing/local/trusted-apps — List, add or remove the apps that may take the same-Mac handoff

Self-hosted macOS only, native loopback and operator bearer. Each entry is a code requirement in Apple's requirement language, as codesign -d -r- prints an app's designated requirement. The list starts empty, which refuses every companion redeem. Changes are recorded as pairing.local_companion.trust_changed.

Bearer: operator

Request body (required JSON)

A JSON value.

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

GET /v1/captain/channel-turns/{deliveryId} — Poll a Discord turn by its stable delivery ID

Bearer: discord text or discord voice

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

GET /operator/v1/voice-call — Device voice call (WebSocket)

WebSocket upgrade the relay opens for an authorized device (VUH-2682, ADR 0288). Binary frames are 24 kHz mono s16le PCM both ways: microphone up, his speech down. Text frames are VoiceCallClientEvent (playback acknowledgements, hangup) and VoiceCallServerEvent (state, playback start/finish/stop, transcript lines, ended) from @clankie/protocol. The call runs the Discord rooms' realtime voice session; ask_clankie becomes a queued turn in the main conversation, each closed transcript line is recorded there without a turn (VUH-2752), and the call holds his voice body lease.

Bearer: captain

POST /operator/v1/dispatch — Operator conversation contract

One route, discriminated op: list, roster, get, create, fork, close, send, cancel, pending_messages, stop_task, replay, subagent_replay, tail, autonomy, terminal_tail, readopt_seat, worker_reports, and acknowledge_worker_reports. worker_reports optionally selects 1–100 exact UUID deliveryIds within the requested conversation, with the existing full-page byte budget and offered-only acknowledgment. Without that selector it remains oldest-first. Unknown, read and foreign IDs are omitted. Worker ownership/report operations require current operator authority and an exact conversationId. Re-adoption proves the original owner and same native thread. Worker reads return complete bounded unread payloads and ackDeliveryIds without acknowledging; only fully offered IDs may be marked read, and the result lists unanswered IDs whose worker has had no reply from that conversation. Roster/fleet report summaries survive disappeared panes, and delivery receipts never establish reading. The TUI and relay both speak this. Built-in tracker sync uses additive op tracker_sync: bootstrap, batch, subscribe, list_issue_views, list_issue_view_issues and keyed atomic transaction commands. Saved-view reads name an exact storeId and project UUID; apply also names the saved view id. They delegate to canonical current list/apply tools and return issue_views or issue_view_issues with hasNextPage and an optional cursor (limit 1–250, default 50). Reads require current device chat or operator authority; writes require terminalControl/owner authority and stamp the authenticated actor. Bootstrap returns JSON lines in result.ndjson ending in cursor/count metadata; the relay emits them as NDJSON. Subscribe returns ordered commits after (storeId,lastSyncId) and waits on publication for at most 20 seconds. The existing relay tail route streams these pages. A cursor/store gap requires partial bootstrap. Each commit and its receipt share the existing atomic tracker write. Owner asks use input_list (optional status and conversationId) to return {questions: [ConversationQuestionResult, ...]}, input_get to read an immutable target, and input_answer or input_cancel to resolve it. All require authenticated operator or active terminalControl device authority; a captain bearer receives 403 question_owner_required. Decision, approval, owner_action, verify and gate asks carry their source conversation, waitingOn, recommendation, options and exact steps as applicable. Built-in tracker gate asks name a run and block it until the owner chooses Approve. Decline, cancellation and free text leave it blocked; item/run references link the same ADR 0245 record rather than another ask store. Escalated worker questions pin native session/request/question IDs; worker answers use an ID-keyed answers map, never terminal typing. Duplicate answers reconcile the original receipt and never send twice. Informational owner mail uses owner_update_list (optional conversationId and unread/read/dismissed/all state; default nondismissed) to return {updates: [OwnerUpdate, ...]}, newest first up to 1000 records. owner_update_read and owner_update_dismiss select an exact update UUID and return {status, update?, reason?}. These use the same owner authority as asks; captain-only callers receive 403. Reading/dismissing is idempotent and never resumes a conversation. Updates are created only when Clankie deliberately calls mail_owner_update; no automatic event feed. Updates carry title, short body, source, timestamp, read/dismissed state, and optional links/media. Asks and updates carry optional issue: {tracker, key, url} for navigation without tracker authority. Each source conversation retains active updates and 32 dismissed records within 256 total records and 512000 bytes; capacity refuses new mail. Native message controls require owner operator authority or an active terminalControl device. pending_messages takes conversationId and a command: list; edit with original messageId, expectedVersion and text; remove or send_now with original messageId and expectedVersion. It returns ordered messages (messageId, version, text, createdAt, state) and an explicit outcome. New native Queue messages are host-owned until pickup; edits, removal and send-now cannot replace a dispatched or uncertain original. Restart retains queued records for explicit send-now and marks interrupted dispatch uncertain. stop_task takes conversationId and returns stopped, already_finished, unsupported, unavailable or uncertain, with taskId when known. Controller-owned Codex uses exact turn/interrupt plus observed native completion. Interactive Claude sends one guarded Esc only with an empty input line. A confirmed unsent draft returns unavailable with typed reason unsent_draft, without sending a key or clearing the text; open the agent's terminal to review it. Clients match reason, never diagnostic detail. Other native stop controls currently return unsupported. Typed reasons require request includeReason: true; absent or false preserves the legacy result shape. Old strict services or relays reject that field with HTTP 400 before dispatch; retry only that schema refusal once without the field, never a lost response or other failure. After Stop dispatch, unexpected errors return uncertain, never HTTP 400. The canonical schemas are in packages/protocol/src/operator-conversations.ts and packages/protocol/src/operator-service.ts. Project onboarding uses project_proposal_get for one defaults-first proposal, project_proposal_tweak for exactly one reviewed field, and project_proposal_confirm for explicit acceptance. Tweak requires the current immutable target and change: { field, value } (name, roles, workerCap, or tracker); it returns a fresh proposal target without saving project/tracker settings. Accepting an old target refuses. These operations require the original owner; captain bearers and preference answers cannot save a project. Acceptance uses the durable CREATE boundary, saves confirmed roles, and never hires workers. The autonomy command reads or sets the master Auto switch for unprompted work (projects on Auto and self-wakes, ADR 0264) and clears a pending self-wake. Turning Auto on requires an operator credential or active terminalControl device authority; a captain bearer alone receives 403 goal_owner_required. Service goals were retired by ADR 0264. 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 and state_work 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. Seat-control operations return 503 with herdr_unavailable when the default runtime is unavailable; ordinary conversations and their durable records remain accessible. presence returns a strict snapshot with mood (needs_you, thinking, in_voice, playing, leading, idle, in that precedence), detail, since (source start timestamp or null when unknown), activeSeats (working seats in the last completed fleet projection; a read never waits for a fresh one), and optional pendingOwnerItem (oldest unanswered owner ask: conversationId, questionId, title, since). It uses optional cursor and waitMs (0–30000); an absent or changed cursor returns immediately. A current cursor parks until the projected sources change, sampled within 500 ms, or the wait expires. Unreachable is a client transport state, never a mood. Paired hosted devices may read it. includeFace true opts in to an optional face (legacy reads omit it). It drives the desktop screen separately from mood/body: needs_you, error, new_message, working or voice, in that precedence. Working follows thinking/leading or observed native captain/child work; voice follows in_voice. Otherwise idle/play omit the override. Live committed captain replies in owner conversations show new_message for 10s; failed owner turns show error for 30s or until the same conversation completes successfully. History, room, worker and fork activity do not raise these transient faces. Face expiry changes the cursor; clients honor Reduce Motion with a static face. Optional expression is a transient desktop action with UUID id and ISO expiresAt: kind emote adds animation (a hero sprite tag), kind say adds text (1–200 characters), and kind move adds x/y (normalized 0–1 on the current display, left-to-right/top-to-bottom). Expiry or owner quiet hours removes it and changes the cursor without changing the mood. Clients discard expired actions even while disconnected, honor Focus, and never take keyboard focus to show an expression. fleet prefers one cursor-coherent snapshot, with one retry and a five-second display observation budget. An incomplete snapshot carries optional readWarnings: {source, reason, message}[], where reason is timeout or changed_during_read. Sources name the pending Herdr fleet (herdr:FLEET_ID), native_fleet_projection, checkout_observations, or fleet_consistency. Seats and personas reflect the last available observation, never fresh admission or ownership proof. The returned cursor remains the cursor from before the read so the next poll can catch changes. roster answers within three seconds; a projection still running leaves its seats as the last completed projection and adds the same optional readWarnings. Optional view: home omits historical personas that are neither seated contacts nor channel participants. Seats, channels, tallies and edges are unchanged. Omitting the selector preserves the full directory; personas and conversation IDs still address retained history. set_persona_role (personaId, role: a built-in such as planner, designer, builder, tester, reviewer or researcher, or a custom role of 1-24 letters, digits, spaces and hyphens; null clears) returns the updated persona and rides the steer grant (ADR 0208). Roles are trimmed and whitespace-collapsed, built-ins fold to lowercase, and custom roles keep their casing and compare case-insensitively. roles returns the built-ins, then custom roles in use, as { role, builtIn, count }. Fleet seats may carry subagents (running count and up to eight recent labels) for local Claude, Codex and registered OpenCode seats that were hired or whose chat is open. Recent entries optionally carry native id, startedAt and endedAt; absent means unknown. work_items takes an optional case-insensitive label; items may carry optional backend-native parent metadata. work_item_write requires the original owner with terminalControl and request {repoId,itemId, requestId UUID,command}. Commands assign work-metadata owner, add/remove a role label, or append a dependency. work_item_write_receipt takes repoId,itemId,requestId and reads the original scoped result. Both return an accepted envelope with receipt {requestId,outcome:applied|refused|uncertain, message,item?}. Repeated IDs and receipt reads never replay a write. subagent_replay takes replay with the parent's existing seat/persona conversationId, a native subagentId, surfaceClientId and the ordinary replay paging options. It needs only the chat grant and returns subagentId plus the ordinary normalized replay result. It reads a bounded local child window through the parent's native source without creating a conversation or granting send, resume or terminal control. Missing locators, changed parents and remote children return typed recovery. Older hosts may reject this operation while their fleet remains readable. replay optionally takes direction: backward, turnLimit (1..40, default 20) and limit (1..500, default 500 for backward). Omit cursor to open the newest window; pass the page's previousCursor as the next exclusive upper bound to load older history. Events remain chronological. hasOlder and hasMore say whether more retained history precedes the backward page. nextCursor is still the newest event in that page and can resume an ordinary forward tail. The event ceiling wins when one turn exceeds 500 events. Omitted direction preserves forward replay and tail behavior. Clients keep distinct older-history and live-tail cursors. terminal_catalog lists up to 48 panes per execution connection (16 connections). Each row carries runtime identity separately from Herdr workspace/tab IDs. Named terminal addresses pin their endpoint; tail, control and input refuse disabled or changed connections with a typed unavailable result, without falling back to the default fleet. Terminal catalog/tail require the relay's terminalObserve grant; control/input require terminalControl. connections reads bounded runtime and account metadata or manages named runtime connections. Commands are list, connect_runtime (id, session), reconnect_runtime, disconnect_runtime (id). It requires the operator captain lane; the device relay requires steer. No provider credential, socket path or session capability is returned.

Bearer: captain or operator or device

Request body (required JSON)

List conversations

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

List live Herdr seats

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

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

Open the newest 20 turns

{
  "op": "replay",
  "schemaVersion": 1,
  "replay": {
    "schemaVersion": 1,
    "conversationId": "replace-me",
    "surfaceClientId": "yaak",
    "direction": "backward",
    "turnLimit": 20,
    "limit": 500
  }
}

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/evaluator — Independent evaluator status, queue and recent reports

Bearer: operator

POST /v1/captain/evaluator — Enable, disable, focus or retry the independent evaluator

Bearer: operator

Request body (required JSON)

A JSON value.

GET /v1/captain/issue-metrics — Observed issue and fleet efficiency with explicit source coverage

Read-only projection of retained exact local native bindings, native transcripts, settled turn metrics, seat ledger edges and unresolved hire receipts. Unknown totals are null and partial/unsupported sources are explicit in coverage. No transcript, command or credential is returned. Window selects observed landing, otherwise approval time or latest unfinished observation; totals cover the selected episode. Passed seat edges never establish approval.

Bearer: operator

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

POST /v1/captain/seat-migrations — Prepare, inspect, claim or complete an exact native session handoff

Preparation persists a conversation execution hold and original process lifetimes. Claim proves every old process exited and matches the exact session, profile and cwd, then records one launch attempt. Unknown receipts or uncertain launches stay held; no action replays a call or signals a process. Completion requires that same session/profile/cwd to be bound and ready. Other conversations continue normally.

Bearer: operator or captain

Request body (required JSON)

A JSON object.

GET /v1/captain/seat-bindings — Inspect binding mode, live operator launcher inventory and recovery

Read-only operator-lane diagnostics. Includes local launcher PIDs and kernel lifetimes, bound/unbound status and exact migration recovery; never contains launch secrets. Observe admission records the same refusal while preserving preparation-release access. An incomplete census or unbound seat holds an enforcing update.

Bearer: operator or captain

PUT /v1/captain/seat-bindings — Bind a launcher's native harness to an operator conversation

Local process proof is required in addition to operator authentication. The request socket identifies the controller. The harness's bridge must present x-clankie-bridge-claim on subsequent MCP and seat mailbox requests. Remote relay and bearer-only clients cannot establish this local binding. Registry refusals include an error code and human-readable recovery text.

Bearer: operator or captain

Request body (required JSON)

A JSON object.

DELETE /v1/captain/seat-bindings — Release the requesting launcher's operator seat binding

Only the registered controller process may remove its binding.

Bearer: operator or captain

GET /v1/captain/seat-context — Resolve an operator seat to its service conversation and workspace

Bearer: operator or captain

POST /v1/captain/seat-context — Create a separate workspace chat for a new native operator seat

Bearer: operator or captain

Request body (required JSON)

A JSON object.

POST /v1/seat/transcript — Append redacted native seat display records to its selected conversation

Bearer: operator or captain

Request body (required JSON)

A JSON object.

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, fleet, address, model; omitted, it is the session's standard sections (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. An explicit conversationId adds that workspace's agent instructions with source paths.

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 notes reach only the operator lane. An empty store still returns a labeled card. 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 and conversation. DELETE ends the session. clankie mcp is the stdio bridge to this route (ADR 0152). An operator request without conversationId opens a stateless session: connected-service tools remain available on the bearer, with no default conversation. Conversation-scoped lead tools refuse with a typed conversation_binding_required tool result and perform no lead operation. An operator request naming a conversation requires the local native binding registered by its launcher and the bridge's x-clankie-bridge-claim. Seat event polling, acknowledgment and reply always require that binding. Joined seats use their authenticated delegated /v1/fleet/lead/mcp route; the device relay does not expose operator MCP or local seat bindings.

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). The launcher registers the native seat binding before polling; clankie mcp asks again when 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. The loaded bridge advertises capabilities through x-clankie-seat-capabilities. No handshake means the strict legacy wake/watch/escalation/message schema; owner turns use a message with content attribution and no ownerOrigin field. The original ID and receipt remain the same. Only declared wire kinds and fields are dispatched. A stale bridge or unacknowledged owner turn produces a visible /mcp reconnect notice in the conversation, without replay. The operator seat_bridges dispatch read exposes the same loaded capabilities used by doctor and status; installed files are not proof of loaded code. A recently interrupted bridge reports reconnecting, then current when its original head resumes current-protocol polling; recovery never changes authority. Host-authenticated owner sends on capable bridges arrive as kind: turn, with ownerOrigin recording the verified device/operator principal and self-reported surface. The seat answers normally in the synced conversation; these events have no separate reply target. Room escalations retain their reply routing.

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

GET /v1/fleet/seats/{paneId}/peers — List native seats in the calling worker's fleet

Requires the local process listener or registered remote relay's exact native pane/session proof. Operator and fleet bearers alone do not identify a peer sender. Returns sender and recipient seat IDs, panes, harnesses, titles and native binding hashes. The owner setting fleet.peerMessages=off refuses discovery. No workspace or account authority is granted by a peer message (ADR 0213 amendment).

Bearer: none

GET /v1/fleet/seats/{paneId}/messages/{id}/status — Read original sending seat's current durable delivery stage

Read-only; never resends, acknowledges a report or reconciles a send fence. Requires the original pane and native binding. Unknown status does not prove nothing was sent.

Bearer: none

POST /v1/fleet/seats/{paneId}/peer-messages — Send one same-fleet peer message through native seat delivery

Uses the same native delivery path as message_seat, with server-authored sender attribution and agent-output framing. Requires native process admission, the sender binding, and the exact same-fleet recipient binding returned by peers. Rechecks the owner switch and native bindings before dispatch. Persists the original delivery UUID before sending. Uncertain attempts reconcile through GET only; neither a duplicate UUID nor a new follow-up replays the original. Records exchanges and receipts in the service audit and Clankie's agent-role transcript without an owner turn.

Bearer: none

Request body (required JSON)

{
  "schemaVersion": 1,
  "seatId": "pc/recipient-terminal",
  "recipientBinding": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "text": "The shared interface is ready.",
  "delivery": {
    "id": "10000000-0000-4000-8000-000000000001",
    "binding": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

GET /v1/fleet/seats/{paneId}/peer-messages/{id} — Inspect the original peer delivery receipt without resending

Requires the original sender's native process/session, original binding, delivery UUID and fingerprint. The fingerprint covers recipient seat, recipient binding and normalized text. Available while peer messaging is off. May match the original native transcript or exact channel/hook acknowledgment; absence of proof remains uncertain while the original recipient is bound. A lost recipient binding settles to recipient_gone with outcome unconfirmed: delivery remains unknown, never resends, and no longer blocks fresh messages. An original still unproven after 15 minutes settles to superseded with outcome unconfirmed: delivery remains unknown and is never resent, and the sender's next message to that seat goes out as a new message labelled as following it. An unresolved original blocks only new messages to its own recipient. Older settled bodies are pruned after 100 messages; exact compact receipts and unresolved originals are retained.

Bearer: none

POST /v1/fleet/seats/{paneId}/review-candidates — Submit the seat's exact patch to its project's standing reviewer

Requires the same native process/session proof as peer messages; the author is attributed from that proof, never from the body. The body carries git diff --binary bytes (base64, at most 4 MiB) and the bridge's git patch-id --verbatim; the service recomputes the hash over the bytes it stores and refuses a mismatch. It sends a review packet to the first live reviewer seat that is not the author. An author's earlier candidate for the same issue becomes superseded. ADR 0287.

Bearer: none

Request body (required JSON)

A JSON object.

GET /v1/fleet/seats/{paneId}/review-candidates/{id} — Read a candidate and its stored patch as its author or reviewer

Requires native seat proof. Only the author and a seat that currently holds the project's reviewer setting may read the patch; others get not_reviewer.

Bearer: none

POST /v1/fleet/seats/{paneId}/review-verdicts — Record APPROVE or CHANGES for one exact patch

Requires native seat proof from a seat that currently holds the project's reviewer setting; the author's seat or occupant is refused. patchId must equal the candidate's stored hash. CHANGES needs at least one finding. The verdict reaches the author's seat and, as a notice that asks for no action, the author's lead. A superseded or already decided candidate refuses. The record flags sameHarness when author and reviewer share a harness. ADR 0287.

Bearer: none

Request body (required JSON)

A JSON object.

POST /v1/fleet/seats/{paneId}/hook — Report a hired seat's lifecycle hook

The clankie-worker plugin's hooks, forwarded by clankie seat-hook from inside the seat's pane (VUH-1458). A Stop or StopFailure settles the seat's turn for its adapter and any completion watch, with the harness's own final text as lastMessage. The session must be the Claude session herdr reports in that pane. Lifecycle reports accept the operator or bound fleet lane. Only native process proof from the request transport can register or drain a next-turn receiver. UserPromptSubmit may return additionalContext and messageIds, with deliveryStage uncertain until the hook writes stdout and posts deliveredMessageIds on the same session. That acknowledgment confirms bridge delivery, never model consumption. Held mail expires within 24 hours; an uncertain take is never replayed. NativeActivity is a separate original-native child-activity report: it requires transport process admission and the exact native producer PID, session, instance timestamp and increasing sequence. It expires after fifteen seconds and never settles a turn, drains mail or grants authority. Its bounded children list carries exact local agent IDs, native state and original state-change time. Claude root turns remain unsupported by this activity projection; a root turn's generated agent ID is not a root proof.

Bearer: operator or captain

Request body (required JSON)

{
  "schemaVersion": 1,
  "event": "Stop",
  "sessionId": "10000000-0000-4000-8000-000000000001",
  "lastMessage": "Tests pass."
}

GET /v1/fleet/seats/{paneId}/tool-catalog — Long-poll a fleet seat's catalog revision

For a worker bridge without the seat channel, such as a Codex seat (VUH-2390). With revision equal to the seat's current catalog revision it parks for up to wait ms (capped at 30000) and returns early when a refresh request, a deploy or the fleet tool and peer settings change it; otherwise it answers at once. The bridge lists its tools only when the revision differs from the one it listed. Never reads or binds the seat's mailbox, and grants nothing. Same pane admission as the mailbox. A service before this route answers 404; the bridge then keeps its five-second check.

Bearer: operator or captain

POST /v1/fleet/seats/{paneId}/tool-catalog — Report the occupying native harness's accepted Clankie tools

A linked Claude mod or Codex startup probe reports raw Clankie bridge names from the actual native session catalog. The service verifies the current pane, harness and session against Herdr, compares the bridge's served expectations and retains a matched/mismatch/unverified diagnostic. This report never grants tools or routes messages. Native probe failures carry error and remain unverified; process liveness is separate evidence.

Bearer: operator or captain

Request body (required JSON)

A JSON object.

POST /v1/conversation-heads — Designate or clear an explicit escalation head

Operator only. Owner must be an existing runnable or canonical room conversation; head must be a writable global/workspace conversation. Rejects self/cycles. Grants no room authority.

Bearer: operator

Request body (required JSON)

A JSON object.

GET /v1/body-leases — Conversation ownership of Clankie's body resources

Operator or active paired device observe grant. Read-only public projection; no incarnation, actor, room text or request content.

Bearer: operator or device

POST /v1/body-leases — Explicitly acquire, renew, release, queue, ask or recover a body resource

Computer ownership uses /v1/computer; this endpoint refuses computer mutations. Strict BodyLeaseRequest protocol union. Operator bound to a selected runnable conversation. Renew/release require the acquisition incarnation. Ordinary release is owner-only and confirms termination; explicit recover uses the current private host claim under operator authority. Queue/ask are bounded notifications and never run body effects.

Bearer: operator

Request body (required JSON)

{
  "action": "queue",
  "resource": "voice",
  "conversationId": "conversation-1",
  "request": "Notify me when voice is free",
  "ttlMs": 300000
}

POST /v1/computer/authority — Recheck the owning conversation's computer authority

Native observation hosts delegate their existing operator bearer and bound conversation to this service before each operation. Uses the same identity and grant checks as /v1/computer, even without a local adapter. A conversation ID is not a grant. Nothing is captured, driven or leased.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/computer — Drive the conversation-leased computer body

Strict ComputerRequestSchema (conversationId, optional joined machineId and command) from @clankie/interactive-environment. Operator authority bound to an existing runnable conversation, rechecked at each input. Actions: status, acquire, renew, release, revoke, recover, inventory, capture, frame, input. Capture returns fresh screenshot metadata and image-pixel coordinate mapping; frame returns bounded PNG media separately. Input is ordered and uses screenshotId plus a persistent requestId; identical retries reconcile, never replay. Failed and uncertain are distinct from confirmed. Expiry/restart/uncertainty retain the lease until host stop proof. An expired local macOS lease also permits explicit operator recover with ownerRecovery {reason, expectedHolder, expectedExpiresAt}. This independently reauthorizes the same operator, requires no service-tracked holder work or computer operation, and syncs a decision audit before exact-incarnation release. It accepts unknown native drain; it does not prove termination. Refusals provide detail and next guidance. Windows and joined screens refuse this override. Local macOS Peekaboo and an explicitly attached Windows native-harness host, read-only unless its owner explicitly sets allowInput true before acquisition; lease and status record that choice. Opted-in full Windows clients capture native accessibility strings and accept one foreground primitive per fresh observation, with an exact changed accessibility postcondition (input.expect.field/equals); scroll also needs an image-pixel at point. Native dispatch alone cannot confirm an effect. Host Win32 person activity is rechecked before input; shell/system targets and system-switching shortcuts refuse. Every native error retires the host. Input release requires James's W8 live stop proof. Observation-only clients remain read-only. No additional model loop starts. A registered joined machineId selects a lent screen without fallback, including from a hosted service. The host requires fresh screen policy within the original join ceiling and local per-session consent; input is off until locally allowed. Its visible pet Stop fences queued input. Authored Mac and Windows hosts support accessibility press/text and bounded navigation key/drag/scroll with exact changed-field receipts. Keys use a named allowlist; scroll requires an image-pixel anchor and 1-10 ticks. Native observer acknowledgments never release a post-input lease; true queue drain remains unknown. Frame chunks share the authenticated join carrier within existing caps. Real Mac/PC driving and native stop proof are live gaps.

Bearer: operator

Request body (required JSON)

{
  "conversationId": "global-default",
  "command": {
    "action": "status"
  }
}

GET /v1/captain/readiness — Read secret-free chat setup readiness

Any active paired device or owner operator may read this. A live native operator bridge reports ready independently of the fallback model. Otherwise the shared captainReadiness rule reports no_model or no_credential, with model and provider ids when known. No credential material or authentication method leaves the body. Responses are no-store.

Bearer: operator or device

Discord

GET /v1/discord/settings — Read Discord server roles, owners, room skills, fleet and tracking

Operator-authorized non-secret settings, their revision and the shared setup definition. Normal setup connects a server with participant or admin, fleetEnabled and trackingLevel (off, project_updates, project_activity, all_issues). Raw IDs and machine grants stay under Advanced. The role-correct invitation and gateway checks are read-only.

Bearer: operator

POST /v1/discord/settings — Save revision-fenced non-secret Discord settings

Requires settings and expectedRevision. servers records role and owners (me, everyone or role with ownerRoleId); roomSkills records a serverId, channelId and known skill. houseHuntingAuthorBindings records explicit household, userId, legacyAuthor and ownerConfirmed=true entries; display names never establish identity. Each household/legacy label binds to one ID. Binding alone changes no feedback; only new ID-attributed reconsiderations record legacy targets. Omitted ownership/binding fields from older clients are preserved. Legacy guild/channel machine grants are retired. Connecting a server projects its ingress, presence and voice scope while preserving machine grants and lab opt-in. Stale writes are refused. Saving never posts to Discord. Admin actions refuse server deletion and ownership transfer at the body.

Bearer: operator

POST /v1/discord/setup/test-post — Explicitly send one owner-requested setup message to a text room

Settings-level operator authority is required; Observe or Steer cannot post. The current settings revision, connected account and Send Messages evidence are checked before dispatch. Reads, setup opening and picker edits never call this operation. Missing native receipts are unconfirmed and never retried.

Bearer: operator

Request body (required JSON)

A JSON object.

POST /v1/discord/ingress — Admit an encrypted Discord turn or scoped voice callback

Remote connection API, not an operator bearer. P-256 ECDH and AES-GCM protect request and response; a 60-second Ed25519 fleet permit binds the tenant, installation, event digest and ephemeral response recipient. Durable delivery dedupe prevents repeated captain effects. Voice callbacks use the existing briefing, attributed captain handoff and three voice self-tools. See docs/discord-ingress.md.

Bearer: none

Request body (required JSON)

A JSON object.

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. reconcile=1 performs a read-only reply-history check for the original admitted message. Returns {reply: result} when found, or {reply: null} only after complete history proves absence. Unknown or stale authority refuses; it never posts or clears an active predecessor's write.

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 memory note and Discord person fact

Notes persist until forgotten. Catalog retention fields remain legacy compatibility metadata and no longer impose a count quota.

Bearer: operator

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