clankie docs

Public network surface

A narrow doorway, not a hosted Clankie.

api.clankie.bot accepts only the routes below. The gateway carries bounded exchanges to an authenticated machine; your machine still owns devices, grants, conversations, and terminal authority.

Connection shape

iPhone or iPad ── HTTPS ── api.clankie.bot ── outbound WebSocket ── your machine

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 your machine. 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 Device bearer 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 a verified device bearer Revoke delivery, including when the former machine is offline.
POST /v1/pairing/redeem One-time offer secret or typed code Claim an active pairing offer and receive a completion token.
POST /h/{hostId}/v1/pairing/complete One-time completion token Accept a subset of the offered grants and activate the device.
GET /h/{hostId}/v1/devices/self Device bearer Read the paired device’s own registration and grants.
POST /h/{hostId}/v1/devices/self/push Device bearer Enable or disable this device’s versioned push reference on its machine.
POST /h/{hostId}/v1/devices/self/session/refresh 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 /h/{hostId}/operator/v1/dispatch Device bearer plus the operation’s grant Send a chat, fleet, steer, or terminal-control operation to your machine.
POST /h/{hostId}/operator/v1/tail Device bearer with chat access Read the app conversation as a bounded long-poll stream.
POST /h/{hostId}/operator/v1/terminal-tail Device bearer with terminal-observe access Read terminal frames from your machine’s supported Herdr integration.

What the gateway does not do

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

Public TLS terminates at the gateway and your machine maintains a separate authenticated TLS connection to it. The gateway is therefore able to read forwarded content in transit even though it does not retain content bodies. Device grants are enforced by your machine on every request. Pairing capabilities expire, are single-use, and are registered at the gateway only by their hashes.

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 the user’s machine. The private local service has a larger contract — the HTTP API — which is served only on your machine, never at the public origin.

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