Public network surface

How your devices reach Clankie.

This reference describes the gateway's allowed host routes. The gateway carries bounded exchanges to Clankie's authenticated host, whether that is your Mac or a managed machine. That host owns devices, grants, conversations, and terminal authority. Account and billing services at the same public origin have separate contracts; this is not a catalog of every hosted-service endpoint.

Connection shape

iPhone or iPad ── HTTPS ── api.clankie.bot ── outbound WebSocket ── Clankie's host

The first pairing redemption uses the stable public origin. Successful redemption returns an opaque, host-scoped origin. Normal app calls use that origin and a device credential minted by Clankie's host. Users do not copy a host id, URL, or bearer token.

Published routes

This table is generated from the protocol package’s production allowlist. The docs build fails when a route changes without a matching access and purpose description.

Method	Route	Access	Purpose
GET	`/health`	Anonymous	Deployment liveness only.
GET	`/gateway/v1/config`	Anonymous	Publish the non-secret Cognito issuer, client id, and enrollment mode.
WS	`/gateway/v1/hosts/connect?hostId=…&installationId=…`	Machine account bearer	Keep one authenticated outbound connection from a Clankie machine.
POST	`/gateway/v1/push/registrations`	Encrypted device proof verified by its machine, plus the app’s delivery key	Register or move versioned APNs delivery when push is configured.
POST	`/gateway/v1/push/registrations/clear`	App delivery key; first allocation also requires an encrypted device proof	Revoke delivery, including when the former machine is offline.
GET	`/v1/body-transfer/status (inside encrypted exchange)`	Encrypted active owner device with Take Control	Read which body holds Clankie: self id, epoch, state and transfer records.
POST	`/v1/body-transfer/freeze (inside encrypted exchange)`	Encrypted active owner device with Take Control	Stop being Clankie for a transfer once idle; the body restarts dormant.
POST	`/v1/body-transfer/bundle (inside encrypted exchange)`	Encrypted active owner device with Take Control	Read one chunk of a frozen body's transfer bundle.
POST	`/v1/body-transfer/stage-chunk (inside encrypted exchange)`	Encrypted active owner device with Take Control	Upload one chunk of an incoming transfer bundle.
POST	`/v1/body-transfer/stage (inside encrypted exchange)`	Encrypted active owner device with Take Control	Verify a complete bundle and stage it for this body.
POST	`/v1/body-transfer/apply (inside encrypted exchange)`	Encrypted active owner device with Take Control	Commit a staged transfer; the body restarts and applies it before anything opens.
POST	`/v1/body-transfer/release (inside encrypted exchange)`	Encrypted active owner device with Take Control	Become a tombstone after the destination reports itself active.
POST	`/v1/body-transfer/discard (inside encrypted exchange)`	Encrypted active owner device with Take Control	Burn a transfer id this body never applied.
POST	`/v1/body-transfer/abort (inside encrypted exchange)`	Encrypted active owner device with Take Control	Return a frozen source to active after its destination burned the id.
POST	`/v1/body-transfer/reclaim (inside encrypted exchange)`	Encrypted active owner device with Take Control	Reactivate a dormant body at a higher epoch, recorded as an explicit override.
POST	`/v1/body-transfer/rebind (inside encrypted exchange)`	Encrypted active owner device with Take Control	Point transferred workspaces at the old machine once it joins.
POST	`/h/{hostId}/v1/machine-joins/start`	Unauthenticated bootstrap metadata; grants no machine access	Create an expiring join ticket for a machine awaiting explicit owner approval.
POST	`/h/{hostId}/v1/machine-joins/status`	Join claim-secret bearer	Read approval state and retrieve the sealed machine lease after owner consent.
POST	`/v1/machine-joins/approve (inside encrypted exchange)`	Encrypted active owner device with Take Control	Approve a join code with an explicit access level and directory scope.
POST	`/h/{hostId}/v1/joined-machines/challenge`	Joined machine identifier; grants no operation authority	Obtain a short-lived challenge for an authenticated machine exchange.
POST	`/h/{hostId}/v1/joined-machines/channel`	Authenticated machine envelope with a fresh challenge	Poll scoped operations and return machine results under the current owner policy.
POST	`/h/{hostId}/v1/joined-machines/leave`	Authenticated machine envelope with a fresh challenge	Revoke the joined machine lease and confirm departure.
POST	`/h/{hostId}/v1/activity/viewer`	Fleet-signed Activity media permit with current audience authorization	Read the scoped hosted Activity stream while its live audience remains authorized.
GET	`/v1/composer/transcription/status (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Read composer transcription availability and included recording allowance.
POST	`/v1/composer/transcription/begin (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Begin a bounded, device-scoped composer recording.
POST	`/v1/composer/transcription/chunk (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Append a bounded recording chunk at an exact byte offset.
POST	`/v1/composer/transcription/commit (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Request one transcription for an editable draft; sending stays explicit.
POST	`/v1/composer/transcription/cancel (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Discard that recording and prevent late draft delivery.
POST	`/v1/composer/transcription/receipt (inside encrypted exchange)`	Active ordinary paired device bearer with chat access; encrypted exchange only	Recover the same draft receipt without repeating provider dispatch.
GET	`/v1/devices/self/diagnostics-default (inside encrypted exchange)`	Operator or paired device bearer	Read the account's diagnostics default the device inherits; no other settings.
GET	`/v1/captain/readiness (inside encrypted exchange)`	Operator or paired device bearer	Say whether Clankie can answer and, if not, the secret-free setup reason.
POST	`/v1/hosted/operator (inside encrypted exchange)`	Encrypted live device bearer with account-paired operator authority	Run a bounded operator request on the hosted body; device revocation and inner route validation remain authoritative.
POST	`/h/{hostId}/v1/discord/ingress`	Fleet-signed scoped permit and P-256 encrypted request and response	A trusted Discord connection delivers a sealed addressed turn
GET	`/v1/model-keys (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the supported model catalog, Clankie model selection and stored-key status, never keys.
GET	`/v1/model-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the persisted model preference, actual provider/model identities, funding, eligible choices, availability and read-only automatic routing targets. Missing hosted identity is unknown; unresolved catalog and credit-rate policy is explicitly labeled.
POST	`/v1/model-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Set or restore an eligible provider/model preference through the shared settings API for CLI, TUI and app. Changes persist and apply to new turns; an active turn keeps its configuration. Routine and escalation targets are read-only, and unavailable choices are rejected.
POST	`/v1/model-keys/set (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Store or replace a provider API key in the body credential broker.
POST	`/v1/model-keys/validate (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Check a stored provider key with a bounded provider request; return only a success or error code.
POST	`/v1/model-keys/select (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Choose Clankie’s model for its next turn using the shared CLI config.
POST	`/v1/model-keys/remove (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Remove a stored provider API key without exposing it.
GET	`/v1/model-keys/subscriptions (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Name the providers signed in through an account (OAuth or subscription), without token details.
GET	`/v1/model-keys/subscriptions/methods (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	List sign-in methods allowed by the body's provider policy.
GET	`/v1/harness-logins (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read whether the Claude Code and Codex worker harnesses are installed and signed in.
POST	`/v1/harness-logins/start (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start a worker harness's own login (Claude subscription or Codex device code) for this device, in the default, a named or a new profile.
POST	`/v1/harness-logins/status (inside encrypted exchange)`	Encrypted initiating device bearer with terminalControl (Take Control)	Read this device's transient login link/code or the harness sign-in outcome.
POST	`/v1/harness-logins/code (inside encrypted exchange)`	Encrypted initiating device bearer with terminalControl (Take Control)	Send the code Claude's sign-in page showed to the waiting login.
POST	`/v1/harness-logins/cancel (inside encrypted exchange)`	Encrypted initiating device bearer with terminalControl (Take Control)	Cancel this device's pending worker harness sign-in.
GET	`/v1/harness-logins/accounts (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	List every Claude Code and Codex account on this machine with its email, plan, sign-in state and usage.
POST	`/v1/harness-logins/remove (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Sign one non-default worker harness account out with its own logout, deleting it if Clankie created it.
POST	`/v1/model-keys/subscriptions/start (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start a provider sign-in for this device and its chosen catalog model.
POST	`/v1/model-keys/subscriptions/status (inside encrypted exchange)`	Encrypted initiating device bearer with terminalControl (Take Control)	Read this device's transient browser URL/code or sign-in outcome.
POST	`/v1/model-keys/subscriptions/cancel (inside encrypted exchange)`	Encrypted initiating device bearer with terminalControl (Take Control)	Cancel a pending sign-in before its credential write is admitted.
GET	`/v1/model-keys/options (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Name the providers that can serve a turn now and the running model's reasoning effort, without credentials.
POST	`/v1/model-keys/effort (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Set or clear the running model's reasoning effort using the shared CLI config.
GET	`/v1/accounts (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the body-owned GitHub, Linear and Google catalog with account, grants and recovery status, never tokens.
POST	`/v1/accounts/github/start (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start a GitHub device flow on the body; return the user code and verification URL.
POST	`/v1/accounts/github/poll (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Poll a pending GitHub device flow; the body stores the token in its credential broker.
POST	`/v1/accounts/linear/start (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start a Linear OAuth PKCE flow; the verifier stays on the body.
POST	`/v1/accounts/linear/complete (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Hand the Linear authorization code to the body, which exchanges it with its verifier.
POST	`/v1/accounts/linear/app (inside encrypted exchange)`	Encrypted device bearer with terminal-control access	Verify and connect a workspace-owned Linear app; client credentials stay on the host.
POST	`/v1/accounts/disconnect (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Disable local account access and attempt provider revocation; Google disconnect disables all three Google connections and reports pending revocation if needed.
POST	`/v1/accounts/email/connect (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Choose his Clankie mailbox in one step once Clankie's mail service answers this install's Clankie account, and return the email row; otherwise refuse with account_required or unavailable and change nothing.
POST	`/v1/accounts/google/start (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start body-owned Google consent for Gmail, Calendar or selected-file Drive access, with state and PKCE.
POST	`/v1/accounts/google/complete (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Exchange the one-time Google code and selected Drive file IDs on the body; return identity and grants without tokens.
POST	`/v1/accounts/google/check (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Refresh and verify the selected Google account's authorized access and return its recovery status.
GET	`/h/{hostId}/v1/gateway/challenge`	Host routing identity; no device bearer	Obtain a one-use challenge for an encrypted device exchange.
POST	`/h/{hostId}/v1/gateway/encrypted`	Authenticated device-to-host AES-GCM envelope	Carry pairing, conversation, control, artifact and terminal traffic without revealing application bytes to the gateway.
POST	`/h/{hostId}/v1/gateway/push-authorize`	Gateway-internal one-use encrypted device proof	Authorize push delivery at the device’s Mac without exposing its bearer.
POST	`/v1/pairing/redeem (inside encrypted exchange)`	One-time offer secret inside the authenticated pairing envelope	Claim an active pairing offer and receive a completion token.
POST	`/v1/pairing/complete (inside encrypted exchange)`	One-time completion token	Accept a subset of the offered grants and activate the device.
POST	`/v1/hosted/support (inside encrypted exchange)`	Signed single-use hosted account ticket bound to the exact support command	Apply an owner support command and return an authenticated encrypted response.
GET	`/v1/support/grants (inside encrypted exchange)`	Owner operator or active device bearer with terminal-control access	Read the body's customer-issued support grants and lifecycle state.
POST	`/v1/support/grants (inside encrypted exchange)`	Owner operator or active device bearer with terminal-control access	Create a referenced read-state or shell support window of at most 72 hours.
GET	`/v1/devices/self (inside encrypted exchange)`	Device bearer	Read the paired device’s own registration and grants.
POST	`/v1/devices/self/app-metrics (inside encrypted exchange)`	Active paired device bearer	Replace this device/platform's bounded, content-free rolling navigation timing summaries.
GET	`/v1/devices (inside encrypted exchange)`	Operator or paired device bearer	List the owner's paired devices for Settings → Devices.
POST	`/v1/devices/:id/revoke (inside encrypted exchange)`	Operator, or a paired device holding terminal control	Revoke one paired device, including the caller itself.
POST	`/v1/devices/self/push (inside encrypted exchange)`	Device bearer	Enable or disable this device’s versioned push reference on its machine.
POST	`/v1/devices/self/session/refresh (inside encrypted exchange)`	Device bearer	Renew the paired device’s short-lived session.
POST	`/h/{hostId}/v1/hooks/linear`	Linear’s own HMAC signature over the request body	Wake the operator thread when the owner comments on a Linear issue.
POST	`/v1/devices/wake-key (inside encrypted exchange)`	Encrypted live device bearer; managed bodies only	Register this device’s public key for waking its hosted body. Self-hosted bodies return 404.
POST	`/h/{hostId}/v1/hosted/pair-offer`	Single-use fleet ticket bound to the browser key; managed bodies only	Return a signed, encrypted pairing offer to the account page’s browser.
POST	`/operator/v1/dispatch (inside encrypted exchange)`	Device bearer plus the operation’s grant	Send a chat, fleet, steer, or terminal-control operation to Clankie’s host.
POST	`/operator/v1/tail (inside encrypted exchange)`	Device bearer with chat access	Read the app conversation as a bounded long-poll stream.
POST	`/operator/v1/terminal-tail (inside encrypted exchange)`	Device bearer with terminal-observe access	Read terminal frames from the host’s supported Herdr integration.
POST	`/operator/v1/artifacts/download (inside encrypted exchange)`	Encrypted device bearer plus chat grant	Download exact bytes of a delivered artifact scoped to its conversation.
GET	`/v1/body-leases (inside encrypted exchange)`	Device bearer with terminal-observe access	Read the active body leases and their ownership on the paired host.
GET	`/v1/discord/rooms (inside encrypted exchange)`	Device bearer with terminal-observe access	Read the Discord rooms and their routing state on the paired host.
GET	`/v1/discord/settings (inside encrypted exchange)`	Device bearer with terminal-observe access	Read the host's Discord settings without credentials.
GET	`/v1/discord/official (inside encrypted exchange)`	Device bearer with terminal-observe access	Read this computer’s free official-bot status, server, blocks and limits. Changes require the operator bridge.
GET	`/v1/discord/directory (inside encrypted exchange)`	Device bearer with terminal-observe access	Read the Discord guild and channel directory available to the host.
GET	`/v1/discord/room-voice (inside encrypted exchange)`	Device bearer with terminal-observe access	Read the selected Discord room's current voice state.
GET	`/v1/discord/voice-transcripts (inside encrypted exchange)`	Device bearer with terminal-observe access	Read bounded voice transcripts for the selected Discord room.
POST	`/v1/discord/room-guidance (inside encrypted exchange)`	Device bearer with steer access	Update owner guidance for a Discord room through its paired host.
POST	`/v1/discord/setup/test-post (inside encrypted exchange)`	Device bearer with terminal-control access	Send the bounded setup test message through the paired host's Discord body.
GET	`/v1/linear/follow (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the following switch, webhook readiness and current revision.
POST	`/v1/linear/follow (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Set the following switch against its current revision; enabling requires the signed webhook.
GET	`/v1/linear/wake (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read signed activity actor and event wake rules and their current revision.
POST	`/v1/linear/wake (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Replace wake rules with revision fencing; rules apply to new signed activity without replaying history.
GET	`/v1/operator/work-tracker (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the default work tracker or an exact project's saved choice without a mutation request.
POST	`/v1/operator/work-tracker (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read or preview a work tracker choice, then confirm a revision-bound global default or project change while retaining existing items.
GET	`/v1/operator/fleet-settings (inside encrypted exchange)`	Encrypted live device bearer with terminalControl (Take Control)	Read the owner's fleet size, models, work closure and machine setup responsibility.
POST	`/v1/operator/fleet-settings (inside encrypted exchange)`	Encrypted live device bearer with terminalControl (Take Control)	Update fleet settings against the current revision and owner authority.
GET	`/v1/captain/seat (inside encrypted exchange)`	Owner operator or paired device holding terminal control	Read the next explicit app, Claude Code or Codex launch choice and whether this Mac supports it.
POST	`/v1/captain/seat (inside encrypted exchange)`	Owner operator or paired device holding terminal control	Save a revision-fenced own-seat choice on this Mac, independently of worker preferences; does not launch or move a session.
POST	`/v1/captain/seat/start (inside encrypted exchange)`	Owner operator or paired device holding terminal control	Open the selected seat in a fresh local conversation and, for Claude Code or Codex, a new native Herdr tab; retain the caller's request UUID to prevent duplicate launches.
POST	`/v1/captain/seat/status (inside encrypted exchange)`	Owner operator or paired device holding terminal control	Reconcile the original start UUID after a lost reply or service restart; a created pane is only starting until its requested native bridge connects.
GET	`/v1/operator/fleet-settings/hire (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read harness, model and effort defaults; omitted fields leave the choice to Clankie.
POST	`/v1/operator/fleet-settings/hire (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Update hire defaults against the whole hire profile revision; auto clears a preference.
GET	`/v1/operator/persona (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read chattiness and reply policy; account-paired hosted operators retain full persona access.
POST	`/v1/operator/persona (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Update chattiness and reply policy; other persona fields require operator authority.
GET	`/v1/worker-accounts (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read sign-in, identity, usage headroom and holds for this machine or the named fleet connection; never credentials.
GET	`/v1/worker-accounts/holds (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read every held worker account and the current holds revision.
POST	`/v1/worker-accounts/holds (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Hold or release one account for automatic hiring; an explicitly selected account remains usable.
GET	`/v1/usage (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read this machine's Claude and Codex usage windows, the run-out warning settings, and the hire allocation: each account's rank, spare capacity per day, projected run-out and reason, plus the next hire per harness; never credentials.
GET	`/v1/usage/settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the usage overlay and run-out warning settings with their revision.
POST	`/v1/usage/settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Show or hide the overlay meters, or set when the lead is warned that an account will run out before its reset, against the current revision.
GET	`/v1/huddles (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	List recent fleet huddles, newest first, each with its compiled landing board.
POST	`/v1/huddles (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Start a huddle that asks every seat where it is, what blocks it and what it will land.
POST	`/v1/huddles/close (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Stop collecting answers for one huddle and compile its board now.
GET	`/v1/operator/views (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	List Clankie's live views: each one's spec, whether it is pinned, and when a temporary one expires. GET /v1/operator/views/:id renders one now, each source's data or why it could not be read, and is 404 once the view has expired.
GET	`/v1/integrate/shipping (inside encrypted exchange)`	Encrypted owner-paired device bearer with terminalControl (Take Control); no visitors or support	Read active integration batches and the latest 30 completed batches: issue keys from commit subjects, commit IDs, check failures, interrupted states and the number waiting to merge. Read-only; no logs, private paths or error details. Returns 503 when the integration queue is unavailable.
POST	`/v1/operator/views (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Create, pin, unpin or expire a view; the relay holds each request and answer to the views schemas.
GET	`/v1/fleet/roster (inside encrypted exchange)`	Encrypted owner-paired device bearer with terminalControl (Take Control); no visitors or support	Read host-observed agent counts by status, machine and lead, each exact native occupant, progress, inactivity and incomplete-source warnings.
POST	`/v1/fleet/roster/retire (inside encrypted exchange)`	Encrypted owner-paired device bearer with terminalControl (Take Control); no visitors or support	Retire a finished or stale exact occupant through kept-report, draft, native-process and work guards; refusals keep the pane, and a confirmed close supplies a five-minute Undo ID. No force override.
POST	`/v1/fleet/roster/undo (inside encrypted exchange)`	Encrypted owner-paired device bearer with terminalControl (Take Control); no visitors or support	Reopen and resume the same saved native agent within its retirement Undo window. An uncertain reply must not be replayed automatically.
GET	`/v1/captain/routines (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	List the owner's routines: each one's schedule, target, missed-run policy, next run and whether it is paused.
POST	`/v1/captain/routines (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Add, edit, pause, resume, run now or remove a routine, or read one routine's run history; a routine runs with the authority of the conversation it targets.
GET	`/v1/settings/evidence-storage (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the configured and active evidence storage destination, its revision and whether a restart is required; never credentials.
POST	`/v1/settings/evidence-storage (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Save the evidence storage configuration with revision fencing; it applies after a restart and never activates storage or sets up credentials.
GET	`/v1/operator/host-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read keep-awake and automatic update preferences, their revision and host capability status.
GET	`/v1/operator/http-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read the exact browser-origin allowlist shared by self-hosted core and relay, and its revision.
POST	`/v1/operator/http-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Replace the browser-origin allowlist with revision fencing; empty disables browser access. Pairing and bearer grants remain authoritative.
POST	`/v1/operator/host-settings (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Save host preferences with revision fencing; managed updates stay on. A saved choice whose runtime application fails returns a validated saved receipt.
GET	`/v1/operator/appearance (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read which bundled skin Clankie wears on the owner's surfaces, and its revision.
POST	`/v1/operator/appearance (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Choose Clankie's look with revision fencing; the id must be well formed, and apps fall back to the selected pack's own look for a skin they do not bundle.
GET	`/v1/operator/voice (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Read stored and effective public voice settings and revision; provider credentials remain private.
POST	`/v1/operator/voice (inside encrypted exchange)`	Encrypted active device bearer with terminalControl (Take Control)	Save a validated voice configuration against its current revision; application requires the active body restart.
GET	`/v1/operator/projects (inside encrypted exchange)`	Encrypted live device bearer with terminalControl (Take Control)	Read project settings, including autonomy overrides when explicitly requested.
POST	`/v1/operator/projects/update (inside encrypted exchange)`	Encrypted live device bearer with terminalControl (Take Control)	Update project settings and fleet responsibility overrides with current owner authority.

What the gateway does not do

It does not run Clankie, a model, a terminal, or a Herdr fleet.
It does not mint device sessions or decide device grants.
It does not expose arbitrary machine paths or arbitrary HTTP forwarding.
It does not retain forwarded content bodies, message content, or terminal frames.

Optional push delivery

When push is configured, the gateway stores APNs tokens, routing identifiers, delivery-key hashes, and versioned revocations. The app’s key authorizes moving or clearing an existing registration, including when its former machine is offline. The machine holds only a registration reference. Wakes carry a fixed alert and host/conversation identifiers, never message text. Apple receives the token, timing, and those identifiers. Pairing and messaging work without push configuration.

Security boundary

Device application requests and responses use an authenticated encrypted envelope between the device and Clankie's host. TLS also protects both connections, but terminating TLS does not let the gateway decrypt device bearers, conversations or terminal bytes. The host enforces device grants on every request. Pairing uses a secure QR or full link whose fragment carries the encryption credential directly to the device; short codes work only on direct private connections.

The gateway can observe routing identifiers, ciphertext sizes and timing, and can interrupt service. Push delivery retains the metadata described above. Cognito sign-in, signed Linear webhooks, managed web pairing and Discord ingress have separate authentication contracts; they are not ordinary device requests inside this envelope. Matching gateway, host and client versions are required; implementation alone does not establish deployment or release readiness.

For integrators

These routes document the product’s observable internet boundary; they are not a general third-party API. Clients pair through Clankie and must use credentials and grants issued by his host. The private local service has a larger contract — the HTTP API — which is served on the host, never wholesale at the public origin.

See the source repository for the current protocol and the privacy notice for data handling.