Skip to content

REST API

github-actions[bot] edited this page Nov 14, 2026 · 5 revisions

REST API

This page covers the REST API clauth daemon --listen serves (Daemon): TLS, devices and pairing, every route and its failures, Web Push, CORS, and the connection limits.

Over HTTPS, clauth daemon --listen 0.0.0.0:8443 serves the feed and the switch, for running the daemon on one machine and a client (clauth-tray) on another. Off unless the flag is passed. TLS comes from this host's lego certificate, on all three platforms clauth supports — macOS, Linux, and Windows. Only two things about TLS differ by platform: where that certificate lives, and how the host's own FQDN is discovered. Both are spelled out below, and --cert/--key skip the derivation entirely for hosts where it cannot work.

  • The address is optional. A bare clauth daemon --listen binds 0.0.0.0:8443, the spelling this page uses everywhere else; pass an explicit ADDR:PORT to bind anything narrower (--listen 127.0.0.1:8443 for a loopback-only listener behind a reverse proxy, say).

    • The shorthand deliberately defaults to every interface rather than loopback, because a listener the remote client cannot reach is not a useful default for this flag.
    • Nothing listens unless --listen is passed either way — the default fills in the value, never the flag.
  • The mod bridge socket. Under --listen the daemon also binds ~/.clauth/bridge.sock, the same-user unix socket the Claude Code plugin's module talks to (Claude Code plugin); a session's via holds mod only while a process on that socket reports it.

    • Linux and macOS only — Windows binds none.
    • Owner-only (directory 0700, socket 0600), no token: any process running as the user can reach it.
    • Unlike the REST bind, a failure here is not fatal: the daemon logs a line starting clauth daemon: no mod bridge (… on <path>: <error> for a bind failure) and runs on without the bridge, so rotation and fallback never stop for it.
  • TLS is not optional. There is no plaintext mode and no flag to ask for one, because a device's bearer token crosses the connection on every request.

    • The certificate is read once at startup from the platform's lego directory (see the next bullet), in lego's own naming: <fqdn>.crt, <fqdn>.issuer.crt, and <fqdn>.key.
    • Any certificate the issuer file adds that the leaf file already carries is dropped, since lego usually writes the whole chain into <fqdn>.crt and a chain that repeats a certificate is malformed.
    • A renewal reaches the listener on the next daemon restart.
    • A missing or unreadable file, or a port already taken, refuses to start rather than running a daemon that looks healthy while the remote client stays dark.
  • Where the certificate lives, and how the host is named, are the only two things that differ across platforms:

    Default certificate directory Host FQDN from
    macOS, Linux /etc/lego/certificates hostname -f
    Windows %AppData%\lego\certificates (C:\Users\<you>\AppData\Roaming\lego\certificates on a stock install) PowerShell [System.Net.Dns]::GetHostEntry($env:COMPUTERNAME).HostName

    The directory is a default, overridable through tls.json (next bullet). The FQDN is not overridable at all — it is whatever the rest of the box already believes it is called, and a certificate issued to a name the host does not answer to would be the actual bug. Point lego at the Windows directory with its --path flag: lego's own default there is .lego under the working directory, which is useless for a daemon, since the working directory is whatever started it. The Windows default is per-user, matching where clauth keeps everything else (~/.clauth) — so a daemon run as you finds it, while one run as a Windows service under LocalSystem would resolve a different %AppData% and needs tls.json pointed at a directory both accounts can read. Note that Windows' whoami /fqdn is not the lookup and could not be one: its "FQDN" is the current user's Active Directory distinguished name (CN=…,DC=…), not the machine's, and it fails outright for a local account.

  • ~/.clauth/tls.json points at the certificates. Written with this platform's default the first time a --listen daemon starts, so there is a real file to edit rather than a documented path to retype:

    {
      "schema": 1,
      "cert_dir": "/etc/lego/certificates"
    }

    Edit cert_dir and restart to serve from anywhere else — a Windows box whose lego lives outside %AppData%, a Linux one following a distribution's own packaging convention, or a staging certificate in a scratch directory. The file is never rewritten once it exists, so an edit survives every restart and every upgrade. A tls.json that cannot be parsed — or that carries an empty cert_dir — refuses to start instead of falling back to the default: quietly serving out of a directory you believe you moved away from is a worse failure than not starting, and the error names the file. Delete it to get the platform default back. A schema newer than this build knows is read anyway (the field it needs is a path either way), so a downgrade does not strand your configured directory.

  • The certificate has to be this host's own. Whichever lookup applies, the certificate the daemon serves must be issued for that exact FQDN — and clients must reach it by that name, https://<fqdn>:8443.

    • A bare IP fails certificate verification no matter what is listening, which is the easy mistake to make once --listen defaults to 0.0.0.0: binding every interface says nothing about which names the certificate covers.
    • If the box's own name disagrees with the name you got the certificate for, the daemon does not fall back or guess — it looks for files that are not there and refuses to start.
    • Two consequences worth planning for: the host needs a real, publicly resolvable FQDN for Let's Encrypt to validate at all, and a client on a LAN needs that same name to resolve to the daemon's reachable address (split-horizon DNS or a hosts entry), since the name in the certificate, not the address you dialed, is what gets checked.
  • --cert and --key skip the derivation entirely. For the hosts where it cannot work rather than merely points somewhere else: on a tailnet node hostname -f answers a name no certificate covers, and tailscale cert <machine>.<tailnet>.ts.net writes a .crt and a .key with no issuer file beside them and none of lego's naming.

    • A --listen address in Tailscale's ranges (100.64.0.0/10, fd7a:115c:a1e0::/48) with neither flag and no lego certificate for this host refuses to start naming that exact tailscale cert command and the two flags to pass, ahead of lego's missing-file error.
    • 100.64.0.0/10 is also carrier-grade NAT space, so the message names the range rather than calling the host a tailnet node.
    • Passing both by path reads exactly those two files — no hostname -f, no tls.json, and no sibling .issuer.crt even if one happens to sit there, so the chain served is the one in the file you named.
    • The pair is required together and only alongside --listen; a lone --cert is a usage error rather than a silent fall back to lego.
    • Everything else is unchanged: clients still dial the name the certificate covers, and the certificate is still read once at startup, so the restart hook below applies to a tailscale cert renewal too.
  • Renewal is yours to automate. Let's Encrypt certificates are valid for 90 days, and clauth does not renew them — it only reads what lego left on disk, once, at startup.

    • So a --listen daemon needs two automated steps, not one: a periodic lego ... renew (cron or a systemd timer on macOS and Linux, a Scheduled Task on Windows, or whatever else supervises the host), and a daemon restart afterwards, since the certificate is never re-read while the process lives.
    • Renewing without the restart is the failure mode to watch for — the daemon keeps serving the now-expired certificate it read at boot, and every client rejects the handshake while the files on disk look perfectly current.
    • clauth daemon --replace --listen is the in-place restart for that hook — --replace composes with --listen, but the hook has to pass both, since a --replace on its own takes over without a listener.
    • One thing that hook cannot recover from: if some OTHER process (not the daemon) holds the port, --replace terminates the daemon first and then dies at the bind, leaving the host with no daemon at all — refresh and auto-switch stop until it is started again. The renewal hook is the one place this bites by construction: whatever binds the port while the daemon is being restarted (a second daemonless listener, a port-hijacking probe) is a squatter the incumbent daemon's death does not clear.
    • A start under --replace --listen is fatal in one more set, after the incumbent is already gone: the squatter bind failure just named, an unreadable certificate under --cert/--key (read above the claim, so it fails before anyone is terminated), and a legacy-token import (below) that cannot write the device list, which leaves auth_token.json in place for the next start to retry. Any other failure shape is fatal without a --replace too; this is the extra set --replace adds.
    • Check clauth daemon --status after the hook, or make the hook fall back to a plain restart on failure.
    • Nothing warns you in advance: a certificate that expires under a running daemon produces client-side TLS errors, not a clauth log line.
  • Devices. Every request but a pairing or a CORS preflight from a listed origin authenticates as one named device, and each device holds a tier fixed on this machine when its code or token was minted: view reads the feed and manages its own push subscription (below, the one durable write the view tier has), control may also switch accounts and drive panes and sessions.

    • A device joins in one of two ways: clauth devices pair <name> [--control] [--sessions] [--no-qr] prints a one-time code for the device to redeem over the API (on a terminal, with a link and a QR code that carry it to the clauth app), and clauth devices add <name> [--control] [--sessions] mints a token here and prints it once, for a client you configure by hand.
    • --sessions (which needs --control) is the trusted-machine grant that lets the device create sessions through the API once [serve] session_creation is on.
    • A token is 32 CSPRNG bytes through SHA-256, hex, so 64 characters.
    • clauth devices lists the devices (--json for an array; each row carries sessions, true when the device holds the grant).
    • clauth devices allow-sessions <name> grants the sessions flag to a control device later (a device without the control tier is refused: revoke it and re-pair with --control).
    • clauth devices revoke <name> removes one, grant and push subscription included.
    • The revoked device's next request gets a 401 with no restart, because ~/.clauth/devices.json is read per request, and its open streams close within seconds.
    • If the push subscription list cannot be read or written, the device is still revoked, but the command exits 1 naming the subscription left behind: nothing is pushed to it, and the next subscription write drops it.
    • Revoking legacy can also exit 1 over the token file from before pairing (below).
    • devices.json (0600) holds each device's name, tier, sessions grant, join time and a SHA-256 of its token, never the token, so a copy of it lets nobody in.
    • The comparison is constant-time over digests, so neither a token's length nor its first wrong byte is observable in the timing.
    • A device with a tier this build does not know, one a newer clauth paired, authenticates and is refused every route that needs a device with 403 device_tier_unknown, and the other devices are unaffected.
  • Pairing. clauth devices pair <name> prints an 8-character code as XXXX-XXXX, drawn from the OS random source over Crockford's base32 alphabet (0-9 and A-Z without I, L, O, U), then waits.

    • The code is valid for 5 minutes, redeems once, and is dropped after 5 wrong tries.
    • A new pair replaces a code still waiting, and the replaced wait exits 1 saying so.
    • The device posts the code to POST /api/v1/pair (below) and gets its token in the answer.
    • Only the code's SHA-256 reaches the disk, in ~/.clauth/pairing.json (0600).
    • The code prints alone on stdout, and --json (clauth devices pair <name> --json or clauth devices --json pair <name>) prints {"code":"XXXX-XXXX","link":"…"} there instead, link null when there is none. The wait reports on stderr: paired '<name>' (<tier>) and exit 0, or exit 1 with the reason (dropped, expired, replaced, or a stdout reader that left before the code printed, which withdraws the code).
    • When stderr is a terminal, a pairing link and its QR code print there before the wait: clauth: pairing link: <app page>#daemon=<host:port>&code=<XXXX-XXXX>, where a bare origin takes / as its page (https://app.example.net/#daemon=box.tail1234.ts.net:8443&code=…) and a page with a path keeps it as written.
    • The app page is [serve] app_url, else the [serve] app_origins entry when the list holds exactly one that counts (an entry the list skips does not) and it is https (Configuration). <host:port> is [serve] public_address, else the listen address the running daemon publishes in status.json (Daemon).
    • --no-qr drops the QR code and keeps the link. A terminal that reports a width narrower than the QR code gets a line naming both widths and --no-qr in the QR code's place, a link too long to encode gets a clauth: no QR code for the pairing link: … line there, and the link still prints.
    • With a daemon running and no link to build, a terminal or a --json run gets one clauth: no pairing link: … line on stderr saying why, naming the key to set where one applies: no published address and no public_address, no app_url and no app_origins entry that counts, several and no app_url, a lone plain-http entry, an app_url or public_address of the wrong form, or a profiles.toml that does not read.
    • A stderr that is not a terminal (a script, a redirect) gets neither the link nor the QR code, so such a run sees only the code on stdout; --json carries link in its stdout object either way, null beside the stderr line saying why.
    • Ctrl-C withdraws a code still waiting and exits 130; a code that already paired, or was dropped, expired or replaced, reports that ending and its exit code instead.
    • With --control the code is a control credential while it is live: whoever enters it first gets control. The link and its QR code carry the same code, so a photo of either is as good as the code until it is used, dropped or expired.
    • Only this host's daemon serving --listen can redeem the code, and pair warns when no daemon is running at all; it then prints no link (link null under --json), whatever public_address holds.
  • Upgrading from the single token. Before pairing, the API had one bearer token in ~/.clauth/auth_token.json.

    • The first --listen start after the upgrade that binds its port imports it as the control device legacy and deletes the file, so the client holding it (clauth-tray) keeps working on the same bytes.
    • A file carrying any tier but control is neither imported nor served, and a file holding no usable token is not imported; daemon.log says which, once per start.
    • If a downgraded clauth later mints a fresh auth_token.json, the next upgraded start hands legacy that token instead, since it is the one the client was given last.
    • A token revoked after its import is never imported again, even from a file the import could not delete: the device list keeps the SHA-256 of the last token it imported.
    • clauth devices revoke legacy also deletes ~/.clauth/auth_token.json when the file still holds the revoked token, so a downgraded clauth started after that has no copy of the revoked token to serve (one already running keeps the token it read at startup until it restarts, which mints a fresh one), and exits 1 naming the file when it cannot delete or read it.
    • A file holding any other token stays for the next start's import, and revoking any other device never touches the file.
    • --print-token and --rotate-token are gone: a digest cannot be printed back, and a rotation is clauth devices revoke legacy followed by a new pair or add.
  • Every route but the pairing needs a device's token, health included (or, for the terminal stream, a ticket it minted).

    • A CORS preflight from a listed origin (below) is the one other parsed request answered before authentication: it runs no route and names none.
    • The slot is taken at accept(), before the TLS handshake and before any token is seen, because refusing at that point is the cheapest refusal available and the alternative is spawning threads for unauthenticated peers without bound.
    • So an unauthenticated client occupies a slot while it is connected, and a 401, a failed pairing or a preflight closes the connection rather than keeping it alive, so it cannot hold one, and every wrong pairing code costs its sender a new connection.
    • What bounds the occupancy is the clock, not the token: a client that connects and says nothing gets only the 10s first-request timeout, not the 120s lifetime, and one that says something unauthenticated is answered and closed at once.
Route Needs What it does
GET /api/v1/health view {"ok":true,"version":"<ver>","schema":2}. schema is the status feed's, so a reader can refuse a daemon newer than it knows.
GET /api/v1/status view The status.json body (Daemon), byte for byte off disk. Conditional: the ETag digests everything in the body except generated_at, so a feed rewritten by a tick that changed nothing answers 304 with no body. ?wait=<secs> on a request already carrying the current tag holds it open until the accounts actually move (capped at 60s, inside the connection's own 120s lifetime), which is how a client follows a switch without polling; a device revoked meanwhile gets a 401 that closes the connection (an unreadable device list: a 500, which keeps it). ?all=1 rebuilds the body to include disabled accounts, which the published file hides but for the active one, never waits, and is still conditional off its own built body's tag. With no file on disk yet (the daemon's first tick has not landed) or one caught mid-replacement, the body is built here from the same caches instead — the single-shot shape — and carries its own ETag the same way.
GET /api/v1/events view One server-sent-events stream, the rest of the connection. It opens with retry: 1000, then event: herdr — data: {"present":true,"panes":[…]} with one {"pane_id","workspace_id","agent","agent_status"} object per herdr pane (the snapshot every connect, reconnect and re-subscribe hands over, so no agent-status change is missed across a gap) or {"present":false} when no herdr socket answers — then, on a Linux or macOS daemon whose bridge is up, event: session.snapshot on every (re)connect, right after herdr, data: {"sessions":[{"session","cwd","interactive"},…],"asks":[{"session","ask","tool","input","agent_id","start_line","held"},…],"prompts":[{"session","prompt","state","reason"?},…]} (every live mod session and its open asks, sessions sorted by id and asks by session, then open order; prompts holds every prompt still queued and each session's 16 most recent outcomes, by session then in the order the prompts were sent, for sessions whose mod reports outcomes; empty while no session's module reports in), and event: session.status / event: session.record / event: session.ask / event: session.prompt frames relaying each live session's state, transcript rows, asks and prompts: session.status data: {"session","state":…} where state is start (with cwd and interactive), turn_start/turn_end (with turn) or end; session.record data: {"session","agent_id","offset","record"}, one transcript row carrying a uuid (a row without one stays history-only), agent_id null for the main transcript else the subagent whose subagents/agent-<agent_id>.jsonl the row and its offset belong to, read from the transcript file (the mod reports a wake and the daemon tails it; an end the daemon accepts normally reads the main transcript and every subagent file already tailed once more, any other close reads nothing more, and the history route holds whatever a close skips); a record over 1 MiB relays as a stub {"session","agent_id","offset","size","truncated":true} to page through GET /api/v1/sessions/<session>, or GET /api/v1/sessions/agent-<agent_id> for a subagent row, and rows written before the session registered stay history-only; session.ask data: {"session","ask","state":…}, opened (with tool, input, agent_id and start_line, the 1-based line an Edit's old_string starts on in the file before the edit, the first match's with replace_all, null for any other tool, when the module could not read the file or it is UTF-16, when its plain search of the file found no match, or more than one without replace_all; and held, true when the module holds the ask for a device answer, false when it went to Claude Code's own dialog at the desk) or closed (with by desk, device, session_end or interrupt, the last for a held ask a control device's interrupt ended; an unheld or released one it ends closes desk); a control device's stream is what holds asks: while one is open, or the last one closed under 5 s ago, the module holds each new ask, and a view device's stream or a push subscription alone never counts; once none is open or inside those 5 s, every held ask goes back to the desk through its wait, stays open and reads held: false from the next snapshot on (no frame of its own; a device answer to it is refused 404 ask_not_found); an ask with held: false closes by desk once its call settles (a question when the desk answers it, a permission ask after its tool ran or was denied, a check with no tool call at once), and a held ask whose wait failed closes at once; session.prompt data: {"session","prompt","state":…} for a prompt the prompt route answered with an id, queued when the route takes it, then once delivered (Claude Code took it) or dropped with reason refused (refused on 3 tries), removed (Claude Code dropped it, e.g. the desk pressed Esc while it waited), unknown (a reload of the module found its submit still out: it may have run) or session_end (the daemon closed the session with it still queued: the session ended, or its module went 40 s without polling, and a module that comes back may still run it); an id a fresh snapshot no longer lists (a daemon restart) gets no further frame — interleaved with event: status frames. Each status frame is the whole published feed, the status.json bytes off disk exactly as GET /api/v1/status serves them, one data: line per line of the file (the client re-joins them with a newline), id: set to the same ETag, one frame each time the tag moves (a tick that moved only generated_at is not a change); before the first tick lands it sends nothing until the file appears. event: pane_agent_status frames relay herdr's pane.agent_status_changed events byte for byte; a pane opened or closed re-subscribes on a fresh herdr connection and hands over a new snapshot. event: terminal_contention — data: {"pane_id":"…","devices":["…","…"]} — says two or more clients are fighting over a pane's control on GET /api/v1/panes/<id>/stream: it changed hands between those devices 3 times within 5 minutes. One frame per pane per 5-minute window; a fight from before the stream opened is not replayed. A : keepalive comment is written after 15 s of silence. The stream ends cleanly at the connection's 120 s lifetime, within seconds of its device's revoke or an unreadable devices.json (the device's row is re-read every 5 s, and a client slow to read what the stream writes delays its own close), or when it falls 64 session frames behind (the reconnect's snapshot restores the live sessions, open asks, queued prompts and each session's 16 most recent prompt outcomes; rows missed meanwhile page through the history route, and older outcomes are not replayed) — no Content-Length, Connection: close — so a reconnecting client gets the current feed and snapshot first again. herdr's socket is resolved once per stream by one herdr status server --json probe, and the daemon targets herdr's default session wherever it was started — every herdr call it makes strips the HERDR_* session variables and passes no session, so a daemon started inside a herdr pane or under systemd serves the same panes either way, and an inherited HERDR_SOCKET_PATH is never consulted; a socket that is absent, refuses, or drops flips to {"present":false} once per transition and the stream keeps serving status frames, retrying the socket every 5 s while it lives; a stream that could not resolve a socket at all stays absent until its reconnect. A browser's native EventSource cannot send Authorization: Bearer, so a web client reads the stream with a fetch-based SSE reader that honours retry:.
HEAD /api/v1/health, HEAD /api/v1/status, HEAD /api/v1/events, HEAD /api/v1/openapi.json, HEAD /api/v1/panes, HEAD /api/v1/sessions, HEAD /api/v1/sessions/<id>, HEAD /api/v1/gateway, HEAD /api/v1/proxies, HEAD /api/v1/push/key view The same status line and headers their GET would answer, with no body and Content-Length: 0 — a deliberate deviation from RFC 9110 §8.6, which would state the length the GET sends. A HEAD /api/v1/status?wait= carrying the current If-None-Match long-polls exactly like the GET; the wait is not skipped for a HEAD.
GET /api/v1/openapi.json view The OpenAPI document for this API. clauth daemon --dump-openapi writes the exact same bytes to stdout and exits 0 without starting a daemon, so CI pins the spec without a listener.
POST /api/v1/switch control Body {"profile":"<name>"} (resolved case-insensitively, against the Claude Code roster alone: a codex name answers 404 profile_not_found, and the chain routes below edit the Claude Code chain alone). Returns {"ok":true,"previous":…,"active":…}. Republishes status.json before answering, so every reader parked on GET /api/v1/status?wait= is woken by the same switch rather than by the next tick.
POST /api/v1/chain/order control Body {"members":["<name>",…]}, the full new order (each name resolved case-insensitively; a member the roster no longer holds drops out). Returns {"ok":true,"members":[…the order that landed, canonical names…]}. Republishes status.json before answering, like the switch.
POST /api/v1/chain/threshold control Body {"profile":"<name>","threshold":<number>}. Sets that chain member's fallback_threshold (finite, 0..=100). Returns {"ok":true,"profile":"<canonical name>","threshold":<number as stored>}. Republishes before answering.
POST /api/v1/chain/wrap-off control Body {"wrap_off":true|false}. Sets the chain-global quota spent behaviour (wrap_off in the feed). Returns {"ok":true,"wrap_off":<bool>}. Republishes before answering; setting the value it already holds still answers 200 and republishes. The feed's fallback.armed (the member the switch has active) is the switch route's to set, never a chain route's.
POST /api/v1/pair no token Body {"code":"<code>"} sent as Content-Type: application/json; case, dashes and whitespace do not matter, and O, I and L read as 0, 1 and 1. Returns 201 {"ok":true,"name":…,"tier":…,"token":…}, the one response that ever carries a token.
GET /api/v1/panes view Every herdr pane on this host joined to the clauth sessions running inside it, on process ids only — the tokens.clauth tag is display and never joins. A row belongs to a pane when its pid is the pane's foreground process group or a process listed in its process-info; its kind is session when that pid leads the group (the pane's own clauth start or clauth resume) or is a listed clauth running start or resume under a wrapper, and delegate for any other listed process (a claude child, a clauth mcp in flight). foreground_process_group_id is null when the pane's process-info did not answer (it closed between the two calls) or when the pane has no foreground job, and the pane's cwd is null when herdr has none. On Windows herdr lists only the pane's agent root, so no session joins there. Herdr absent (not installed, or no server answered on its socket) answers 200 with herdr.present: false, the one fixed sentence naming the state, and panes: [] — never an error. At most 1 + N herdr calls at 2 s each, where N is the pane count. Each pane also carries agent_session_id: the agent's own session id herdr detected in the pane (its agent_session of kind id), the id GET /api/v1/sessions/<id> pages, null when herdr detected none.
GET /api/v1/sessions view A page of the Claude Code transcript index across the shared store and every live isolated store, newest first (updated desc, then id), previews redacted exactly as clauth sessions --json redacts them, each control or bidi-reordering character in a preview reads as a space (dropped at either end), and a preview that costs more than 200 terminal cells or 200 characters (a CJK character takes two cells, an invisible one still costs a character) ends in .... ?limit= 1..=200 (default 50); ?before= the previous page's next_before, an opaque cursor (null on the last page that carries rows). Each row: id (the transcript stem), last_ran_profile (null when unknown), workspace (empty when the transcript records no cwd), updated (ISO-8601 +00:00), first_message/last_message (null when none), title (the session's Claude Code name, set with claude -n or /rename: the newest name recorded in the transcript's last 1 MiB, cleaned and cut like a preview; null when that stretch records none or its newest one leaves no usable name, never an older name), git_branch (the branch of the newest user record in that same 1 MiB that names one, control and bidi-reordering characters dropped; null when none does), store (global or isolated:<profile>), and the two reach fields, via and lacks, always present ([] when empty), optional in the schema: via (an array, sorted: [], ["herdr"], ["mod"] or ["herdr","mod"]; mod when a mod instance holds the id, herdr when a live pane's agent_session_id equals it) and lacks (terminal_mirror, engine_dialogs, plan_approval when the mod alone reaches the session, via exactly ["mod"]; empty otherwise). Stamping the reach costs one herdr pane list at 2 s per listing. No tokens/cost: the full-parse figures are not served. Only the rows on the page are opened (a bounded head and tail read each); the walk itself opens nothing. A malformed before or limit is 400 bad_request.
GET /api/v1/sessions/<id> view A page of one transcript's records, verbatim: {"ok":true,"id":…,"records":[{"offset":<byte offset>,"record":<the JSONL line as a JSON object>},…],"next_before":<offset>|null,"malformed":<count>}, oldest first within the page, the last limit records (1..=500, default 100) whose lines end at or before ?before= (a byte offset; absent or past the end = the file's end; a before inside a line consumes only the lines that end before it). next_before is the start offset of the oldest line the page consumed, a record it served or a line it counted as malformed, and null when that line starts at byte 0 or the page consumed nothing. A line that is not a JSON object (a torn last line mid-write, a blank line, a JSON array) is skipped and counted in malformed, never served and never an error. A page holds at most 4 MiB of records, except that a single record larger than that is served alone, never cut. clauth parses no record: each is Claude Code's own line, handed over as written, so a Claude Code record change never needs a clauth release; clients model the shapes they render. The id is percent-decoded once and looked up among the transcripts the listing shows, never joined onto a path: an unknown or path-shaped id, and a transcript that cannot be opened, answer 404 session_not_found.
POST /api/v1/panes/<id>/prompt control Body {"text":"<non-empty, no NUL>"}. Runs herdr agent prompt <id> <text> without --wait on herdr's default session (the HERDR_* session variables stripped, like every daemon-side herdr call); 200 {"ok":true} says herdr accepted the submission, and the events stream carries what the agent does with it. The pane id in the path is percent-decoded once (a generated client sends w1N%3Ap19); an id not shaped like herdr's <workspace>:<pane> (each half an alphanumeric, then alphanumerics, - or _) answers 404 pane_not_found before herdr is asked. 400 bad_request (no non-empty text, a NUL in it, or not an object), 404 pane_not_found (herdr's agent_not_found or pane_not_found), 409 agent_blocked (the agent is waiting on a prompt of its own; answer it with keys or the terminal stream), 503 herdr_unavailable (herdr not installed, or its server not running: the /panes sentences), 502 herdr_refused for any other herdr refusal, whose output goes to daemon.log and never the body. The audit line records the pane and the text's length, never the text.
POST /api/v1/panes/<id>/keys control Body {"keys":["y","enter"]}, 1 to 32 herdr key names in press order, each 1 to 32 characters of letters, digits, -, + and _ (esc is the canonical Escape; herdr decides which names exist). Runs herdr pane send-keys <id> <key>… on the default session; 200 {"ok":true}. Answers as the prompt route minus the 409: a name herdr does not know is a 502 herdr_refused. The audit line records the pane and the key count, never the names.
POST /api/v1/sessions/<id>/prompt control Body {"text":"<non-empty, no NUL>"}. Prompts the session's mod when a mod instance is live, else the herdr pane joined on the session id (herdr agent prompt <pane> <text>); 200 {"ok":true,"via":"mod"|"herdr"} names which. On the mod path the prompt joins the mod's queue: prompts run oldest first (a poll answer the daemon fails to write puts its prompts back at the front, which can run them after newer ones), one per turn, each tried again at the session's next turn end, or when another prompt reaches it idle, while Claude Code is holding input (a stopped session, a host that ended its input, a --max-turns or --max-budget-usd limit) or the submit fails, and dropped after 3 refused tries; the 200 also carries "prompt":"<id>" once the session's mod has told the daemon it reports outcomes (on its start or any poll; an older mod never does, and its prompts carry no id), and the events stream then follows that id from queued to delivered or dropped. The session id is percent-decoded once; the mod half needs a live bridge, so without one — Windows, or a daemon whose bridge did not start — the route always takes the herdr fallback, which is exactly one live pane whose agent_session_id equals the id. 400 bad_request (no non-empty text, a NUL in it, or not an object), 400 prompt_command (mod path only: a text whose first character past JavaScript's whitespace set is /, which Claude Code reads as a command and refuses from a plugin; the herdr fallback types it into the terminal as it is) or prompt_blank (mod path only: a text of that whitespace alone), 404 session_not_live (no mod instance and no herdr pane on the id, herdr absent included) or pane_not_found (the fallback's pane is gone, or holds no agent), 409 session_ambiguous (more than one live mod instance carries the id, or, with none, more than one pane does; refused rather than handed to either) or agent_blocked (the fallback's agent is waiting on a prompt of its own), 502 herdr_refused (any other herdr refusal; its output goes to daemon.log, never the body), 503 session_busy (the mod's command queue is full, or the session holds 8192 prompts with no outcome yet; the reason says which) or herdr_unavailable (the pane list answered, but no herdr server answered the fallback prompt). The audit line records the session, the via, the text's length and any prompt id, never the text.
POST /api/v1/sessions/<id>/interrupt control Body {} (an empty body is also accepted; anything that is not a JSON object is refused before any work). Interrupts the session's mod when a mod instance is live, else sends esc to the herdr pane joined on the session id (herdr pane send-keys <pane> esc); 200 {"ok":true,"via":"mod"|"herdr"} names which. Through the mod, a held ask the interrupt's abort ends closes on GET /api/v1/events with by interrupt; an unheld or released one closes desk. The session id is percent-decoded once; the mod half needs a live bridge, so without one — Windows, or a daemon whose bridge did not start — the route always takes the herdr fallback, which is exactly one live pane whose agent_session_id equals the id. 400 bad_request (the body is neither empty nor a JSON object), 404 session_not_live (no mod instance and no herdr pane on the id, herdr absent included) or pane_not_found (the fallback's pane is gone, or holds no agent), 409 session_ambiguous (more than one live mod instance carries the id, or, with none, more than one pane does; refused rather than handed to either), 502 herdr_refused (any other herdr refusal; its output goes to daemon.log, never the body), 503 session_busy (the mod's command queue is full; retry after its next poll) or herdr_unavailable (the pane list answered, but no herdr server answered the fallback keys). The audit line records the session and the via.
POST /api/v1/sessions/<id>/asks/<ask> control Body {"decision":"allow"|"deny"} or {"answers":{…},"notes":{…}} (notes optional), exactly one of decision and answers; a null decision, answers or notes reads as absent. answers maps each answered question's exact text to its answer, at least one entry, each a non-empty string; a question left out reads as unanswered. A key is the question text from the ask's input, byte for byte (never trimmed or case-folded), and a multi-select's chosen options go in one string joined with , ("Sans, Mono"). notes maps a question's exact text to a note on it, answered or not; the mod hands each to Claude Code as that question's annotations entry, so the model reads the note with that question, beside its answer or, when the question is left unanswered, on its own. An empty note counts as none. Answers a mod-held ask (its id arrives on the events stream's session.ask and session.snapshot frames); the first answer wins and closes the ask; 200 {"ok":true}. Mod-only — there is no herdr fallback, so without a bridge (Windows, or a daemon whose bridge did not start) a valid body still answers 404 session_not_live, and a session whose mod died while its herdr pane lives is unreachable here. Both path segments are percent-decoded once. 400 bad_request (the body names neither, or both, of decision and answers, a decision other than allow/deny, notes without answers or beside a decision, an answers or notes that is neither an object nor null, an answers object with no entry, an answer or note that is not a string, or a body that is not JSON), 404 session_not_live (no live mod instance with that id) or ask_not_found (no open ask the mod holds with that id on that session), 409 session_ambiguous (more than one live mod instance carries the id) or ask_closed (that ask is already answered or closed); then, once the held ask is found, in this order: 400 answer_wrong_form (a decision sent to a question ask, or answers sent to any other ask; the reason reads a question takes answers, and a permission ask takes a decision.), 400 answer_unknown_question (an answer or non-empty note keyed by anything but one of the ask's question texts; each answer and note must name one of the ask's questions by its exact text.), 400 answer_empty (an empty answer; each answer must be a non-empty string.), 503 session_busy (the mod's command queue is full; retry after its next poll). A refused answer queues nothing and leaves the ask open. The audit line records the session, the ask and decision=<allow|deny>, answers=<n> or answers=<n> notes=<m> (the answer count, and the non-empty note count when there is one), never their text.
POST /api/v1/sessions control + the device's sessions grant + [serve] session_creation Creates a herdr tab in a directory and starts an agent in its pane, so the app can open a session it then drives through the stream, prompt and keys routes. Body {"cwd":"<absolute, existing directory>","profile":"<clauth profile>"?,"kind":"<herdr agent kind>"?,"workspace":"<herdr workspace id>"?,"background":<bool>?,"with_fallback":<bool>?,"prompt":"<first message>"?}: profile and kind are exclusive; neither means bare claude; a profile (codex profiles included) runs clauth start <profile> in the pane; a kind runs herdr agent start … --kind <kind>. with_fallback needs a profile and moves the session along the fallback chain (clauth start <profile> --with-fallback). "background": true opens no herdr tab: it starts a Claude Code background session in cwd (with a profile, clauth start <profile> [--with-fallback] -- --bg, which the daemon then holds like any such session; with none, plain claude --bg on the linked account, which no daemon holds), and prompt is its first message (non-empty, no NUL; background only); it answers `{"type":"background","ok":true,"background_id":"<8 hex>","session_id":""
POST /api/v1/panes/<id>/ticket view 201 {"ticket":"…","expires_in":30}: a one-use ticket for the next row. 400 origin_required with no Origin; 403 origin_not_allowed for an Origin of null, a repeated one, or one that is not UTF-8, whatever [serve] app_origins holds, with that same reason (below).
GET /api/v1/panes/<id>/stream view to watch, control to type A WebSocket (RFC 6455, version 13) bridging herdr's terminal stream for that pane; the pane id in the path is percent-decoded once, like every <id> route. The device tier decides the half you get, never a request parameter: view is bridged onto herdr terminal session observe and control onto terminal session control --takeover. Every control attach displaces the pane's current controller, which gets a terminal.closed record with reason terminal attach taken over; with no controller to displace, the attach is the same as a plain control attach. Server→client frames are herdr's own newline-delimited JSON records verbatim (terminal.frame renders, terminal.closed ends the stream whatever herdr's reason; a displaced controller's reason is terminal attach taken over); client→server frames are herdr's control commands, `{"type":"terminal.input","text"
GET /api/v1/gateway view The managed shunt gateway: the feed's gateway object (Daemon), read from the daemon's supervisor per request rather than off status.json, so it can be one tick ahead of the file. Read-only: no route changes the gateway.
GET /api/v1/proxies view The managed clauth proxies: the feed's proxies array (Daemon), read from the daemon's supervisors per request rather than off status.json, so it can be one tick ahead of the file. Read-only: no route changes a proxy.
GET /api/v1/push/key view The daemon's VAPID public key — the uncompressed P-256 point, unpadded base64url — as {"public_key":"…"}: the applicationServerKey a browser subscribes with. Minted once from the OS CSPRNG on first need and stable after, never re-minted while ~/.clauth/push-vapid-key.der exists, since a new key orphans every subscription.
PUT /api/v1/push/subscription view Body {"endpoint":"<https URL>","keys":{"p256dh":"…","auth":"…"},"events":["blocked","account","window","credit"]?}. Registers or replaces the calling device's one subscription (its own row only) and returns {"ok":true,"events":[…the set that landed, canonical order…]}; events absent = blocked + account. The endpoint must be an https URL on the default port with no user part, whose host is exactly fcm.googleapis.com, web.push.apple.com or updates.push.services.mozilla.com; the p256dh must be base64url of an uncompressed P-256 point and the auth base64url of 16 bytes. This PUT and the DELETE below are the one durable write the view tier can make.
DELETE /api/v1/push/subscription view Drops the calling device's subscription; 200 {"ok":true}. 404 no_push_subscription when it holds none.

Pushes go out only from a daemon serving --listen; CLAUTH_NO_API=1 stops them with the listener. A push fires on a transition, never on a re-read of the same state: a herdr pane moving into blocked (an agent waiting on the user), an account entering a failed login or key state (auth_status broken, or fetch_status AuthExpired for a usage credential that will not heal: an api key or console session the provider rejected, or a setup token the server refused to the usage probe; an expired token that still refreshes is not a failure), and a chain member's 5h, 7d or 30d window reaching the line the fallback chain switches it at, on a fresh reading (on a proxy account, fresh by the date of its 5h and 7d windows, as the 5h alert reads it); and an account's usage-credit cap filling, also on a fresh reading (never for an account serving its own endpoint with its own key, though the feed's credit_capped still reports its cap whatever its credit gate says). A blocked push for a claude session the mod reports comes from the mod's own asks: each new ask pushes unless that session already pushed while another of its asks is still held for a device answer and a control device counts as connected (the /events row above), so an ask opening beside only asks that went to the desk pushes again, and two asks opening together with no control device connected push twice; herdr's pane push covers only a session without a mod; a pane whose session id herdr cannot report (a failed pane list, a pane missing from it, or one with no session id) pushes as a mod-less pane, so a herdr hiccup can double a mod push rather than silence every other agent; a mod session stuck on a dialog the mod cannot see sends no push — the accepted gap. The kinds are blocked, account, window and credit, and a device subscribes to blocked + account unless it names its own set. The payload is the event kind and, when one is known, the account name; nothing else. Each event kind gets its own outbound budget of 30 POSTs per rolling 10 minutes across every device (one POST per subscribed device per event; blocked, account, window and credit each), so a flapping pane can exhaust only blocked's budget and the worst case across kinds is 120 per 10 minutes; delivery runs on its own thread off a bounded queue, so neither the daemon tick nor the herdr follower waits on a push service. The transition latches live in memory, the 5h bell's precedent: a daemon restart re-announces a standing state once, and nothing is persisted. An account deleted and re-created under the same name announces again; a disabled account keeps its latch, so re-enabling it repeats nothing already announced. Endpoints are re-checked against the same three vendor hosts at send (https only, no redirects), so a hand-edited store cannot steer the daemon off the allowlist; a push service answering 404/410 drops the row unless the device has registered a new endpoint since, and revoking a device drops its subscription in the same step.

PUT /api/v1/push/subscription failures: 400 push_endpoint_not_allowed, an endpoint off the three-host allowlist (the reason names the hosts) · 400 bad_request, a body that is not a subscription, an event name this build does not know, a p256dh that is not an uncompressed P-256 point or an auth that is not 16 bytes · 503 state_locked and 500 internal as for the switch. DELETE /api/v1/push/subscription failures: 404 no_push_subscription when the device holds none · 503 state_locked and 500 internal as for the switch. GET /api/v1/push/key answers 503 state_locked only while it mints the key, and 500 internal when the key file does not read, since it is never minted over.

POST /api/v1/switch failures: 404 profile_not_found, unknown profile · 409 switch_refused, because the target is disabled, its credentials were rejected by a refresh (including a transient refresh failure, which the reason names and which may succeed again on retry), its login changed during the refresh into one that is itself about to expire (nothing failed; the reason says to retry in a moment), the live login is one clauth has not saved (on a proxy account, only one that stores a login (an OAuth pair or a setup token) and has no default_divergence of Overwrite or Discard; otherwise the switch goes ahead and drops the live login, which clauth never saves into a proxy account), or the profile disappeared between the config read and the switch itself (the body's reason names the fix, and nothing was changed) · 409 switch_in_progress when another switch is still running · 503 state_locked when another clauth process is holding the state lock, so the same request will work shortly · 503 daemon_stopping when the daemon is stopping, so retry once it is back · 500 switch_failed, an unexpected failure whose reason is a fixed sentence pointing at daemon.log for the full error chain · 400 bad_request, a malformed body. Refusals carry {"ok":false,"error":"<code>","reason":…}.

POST /api/v1/chain/order failures: 400 chain_order_invalid when the list is not a permutation of the current chain (a missing, extra, duplicated or unknown member; the reason names which) · 400 bad_request, a malformed body · 409 edit_in_progress when another chain edit or a switch is still running · 503 state_locked, as for the switch · 500 edit_failed, a disk error whose reason is a fixed sentence pointing at daemon.log.

POST /api/v1/chain/threshold failures: 404 profile_not_found, unknown profile · 409 not_a_member when the profile is stored but not in the chain (the reason says to add it on the Fallback tab first) · 400 bad_request, a malformed body or a threshold that is not finite or outside 0..=100 · 409 edit_in_progress, 503 state_locked, 500 edit_failed, as for the order route.

POST /api/v1/chain/wrap-off failures: 400 bad_request, a malformed body · 409 edit_in_progress, 503 state_locked, 500 edit_failed, as for the order route.

POST /api/v1/pair failures: 403 pairing_refused for every failed redemption (a wrong code, one dropped after its 5 wrong tries, an expired one, or none waiting) with one fixed reason telling the user to run clauth devices pair again, so the answer says nothing about which it was · 400 bad_request, a body that is not {"code":"…"} or a code that is not 8 alphabet characters once normalized, which costs no attempt · 415 unsupported_media_type, any Content-Type but application/json (parameters and case aside) or none at all, judged before the body is parsed, on every config, which costs no attempt either · 503 state_locked and 500 internal as for the switch. Any answer but a 201 closes the connection.

Every route but the pairing can also answer before its own work: 401 unauthorized (with WWW-Authenticate: Bearer) when no paired device holds the bearer (on a ticket upgrade of /panes/<id>/stream, when the ticket fails that row's terms), a path in no row of the table included (a preflight, below, is answered ahead of this); 403 origin_not_allowed when [serve] app_origins is non-empty and a paired device's request carries an Origin the list lacks, ahead of any handler or bearer /panes/<id>/stream upgrade (a ticket upgrade answers its bind's 401 first) and on a path in no row too (null, a repeated header and non-UTF-8 bytes count as unlisted, and their reason says no entry can list them and to open the app from the address it is served at; no Origin passes); 403 control_required when a view-only device calls a route that needs control; 403 device_tier_unknown when the device carries a tier this build does not know; and 500 internal when devices.json cannot be read at all (announced once in daemon.log, not per request).

[serve] app_origins (Configuration) lists the exact origins whose pages may read this API, compared byte for byte. OPTIONS is no route: it is in neither the table above nor openapi.json. An OPTIONS with a listed Origin and an Access-Control-Request-Method header is a preflight, answered before authentication and before any route lookup with one fixed head on every path and for every requested method: 200, an empty body, Access-Control-Allow-Origin: <entry>, Access-Control-Allow-Methods: GET, HEAD, POST, PUT, DELETE, Access-Control-Allow-Headers: Authorization, Content-Type, If-None-Match, Access-Control-Max-Age: 7200 and Vary: Origin, and the connection closes. Any other OPTIONS takes the ordinary path: 401 with no paired bearer, then 403 origin_not_allowed, 405 or 404. With a listed Origin, every other answer the routes give, a 401, a 304, a HEAD and the events stream included, adds Access-Control-Allow-Origin: <entry>, Access-Control-Expose-Headers: ETag and Vary: Origin. With a non-empty list and any other Origin or none, it adds Vary: Origin alone. An empty list adds nothing. Access-Control-Allow-Credentials and a * are never sent. A 400, 408, 413 or 431 written before the request parses, and a stream's 101, carry none of these headers.

The switch is the same action clauth <name> and the MCP tool perform, so it inherits their gates rather than reimplementing them, and the daemon's main loop picks the result up on its next tick through the ordinary reload path.

Connections persist. HTTP/1.1 keeps the connection open unless the client sends Connection: close (HTTP/1.0 needs Connection: keep-alive to opt in), so a polling client handshakes once rather than once per poll. Every response states its own Connection: disposition and carries a Content-Length, and a kept-alive one advertises Keep-Alive: timeout=<seconds left>, max=<requests left>: the figures are what remains of this connection's budget, not a nominal maximum, so a client is never told it has time it does not have. Pipelined requests are served strictly in order, one at a time.

What makes that safe is that framing is never ambiguous: Content-Length is the only accepted framing, chunked transfer encoding is refused outright, two Content-Length headers that disagree are a hard error, and any framing error answers once and closes rather than trying to resynchronize. Those are the conditions request smuggling needs, and none of them is available here.

Limits: 8 KiB of headers, 64 KiB of body, 100 requests and 120 seconds per connection, a 10s deadline on any single read or write, and 32 concurrent connections. The 10s and the 120s are separate bounds and mean different things. A read that times out while the connection is idle between requests is just an idle connection, so the wait resumes up to the 120s budget; the same timeout part-way through a request is a peer trickling bytes to hold a slot, and fails with 408. A connection that has not sent its first request gets only the 10s, since a client that connects and says nothing has not earned the idle allowance. CLAUTH_NO_API=1 disables the listener whatever the flags say, for killing it without editing the unit that passes --listen.

Neither bound is a response-time budget, and a switch is the case where that matters. The events stream is the one answer that consumes the whole lifetime on purpose: it runs until the connection's 120 s and then closes cleanly, so a client sizes its reconnect against the same budget (it ends earlier when it falls 64 session frames behind); the chain routes wait on the same flock as the switch and answer 503 state_locked the same way. The 10s applies to one read or one write, not to the handler between them: POST /api/v1/switch waits up to 25 seconds for the cross-process state flock (clauth's own bound, sized around a macOS Keychain switch) and may run a token refresh after that, so a switch can legitimately take tens of seconds before a single byte of the response is written. Nothing times out — the whole of it sits inside the connection's 120s lifetime — but a client that sets a 10s socket deadline because this page mentions 10s will give up on a switch that was about to succeed. Size a client timeout against the 120s, and treat a 503 state_locked (state lock held) as the retryable answer rather than an abandoned request; a 503 daemon_stopping clears only once a daemon is back.

Readers should follow the same evolution rule as the feed (Daemon): ignore unknown fields, and refuse only on a schema greater than what they know. The OpenAPI document lists these status fields but never as required: active_codex_profile, codex_fallback_chain, codex_wrap_off, clauth_version, gateway, proxies, tps, profiles[].auto_start_queue, credit_billed_families, profiles[].spend, profiles[].extra_usage, profiles[].credit_capped, profiles[].limit_resets, profiles[].limit_resets_read_at, profiles[].disabled, binary_replaced, binary_removed and listen, so a client generated from it also reads the GET /api/v1/status body of a daemon as old as v0.16.0.

Clone this wiki locally