wristcode/docs/api.md

Gateway API

The watch app talks to the gateway over HTTPS with JSON bodies. The TypeScript types in gateway/src/contract.ts are the source of truth, and the watch mirrors them in watch/WristCode/API/Models.swift. Change both together.

The base URL is https://wristcode.gbrown.org. Every route except GET /v1/health and POST /v1/pair needs Authorization: Bearer <deviceToken>. Timestamps are ISO 8601 strings in UTC.

Errors return a non-2xx status with { "error": "<message for a person>" }.

Status	Meaning
400	The request body is wrong
401	The device token is missing or revoked. Show the pairing screen
404	Unknown host, thread, or project
409	The request is stale, for example an approval that was already answered
429	Too many pairing attempts
502	The T3 server rejected the call. The message says why
503	That host is offline

Pairing

wristcode pair on the gateway prints a 6 digit code that is good for 5 minutes. The watch sends it once and stores the token in its Keychain.

POST /v1/pair
{ "code": "482913", "deviceName": "Gabriel's Apple Watch" }

200 { "deviceId": "9b0c...", "deviceToken": "wc_..." }

After pairing, and again whenever APNs hands the watch a new token:

PUT /v1/device/push
{ "apnsToken": "<hex>", "apnsEnvironment": "sandbox" }

204

Debug builds use sandbox, TestFlight and App Store builds use production.

To unpair, the watch revokes its own token:

DELETE /v1/device
204

Feed

GET /v1/feed

200 {
  "needsYou": [FeedItem],
  "working":  [FeedItem],
  "recent":   [FeedItem],
  "hosts": [{ "id": "...", "label": "Mac mini", "status": "online", "error": null }]
}

needsYou holds threads waiting for an approval or an answer, oldest first. working holds running threads, most recently updated first. recent holds threads that completed or failed in the last 24 hours, at most 10. Host status is one of connecting, online, offline, auth_invalid, or incompatible.

FeedItem {
  "hostId": "...", "hostLabel": "Mac mini",
  "threadId": "...", "projectId": "...", "projectTitle": "bill-tracker",
  "title": "Receipt OCR",
  "phase": "waiting_for_approval",
  "updatedAt": "2026-11-01T09:41:00.000Z",
  "lastMessage": "Parser and tests are written. I want to run the suite.",
  "request": PendingRequest | null,
  "via": { "hostId": "...", "threadId": "...", "title": "Check Panama PATH" } | null
}

Threads an agent started for another thread (subagents and delegate_task children) do not get their own cards. When one waits on you, its request moves onto the card of the thread that started it. via names the subagent, request and phase are the subagent's, and the answer goes to the subagent: POST /v1/threads/<via.hostId>/<via.threadId>/respond. A subagent keeps its own card when the gateway cannot find its parent, or the parent already shows a request.

phase is one of starting, running, waiting_for_approval, waiting_for_input, completed, or failed. lastMessage is the agent's latest message trimmed to about 280 characters. It can be null for a moment after a thread changes.

PendingRequest {
  "id": "...",
  "kind": "command",
  "prompt": "bun test --filter ocr",
  "reason": null,
  "options": [{ "decision": "accept", "label": "Allow" }, { "decision": "decline", "label": "Deny" }],
  "questions": []
}

An option may also carry warning, a short note about a risky choice such as "Applies to every thread". For questions (kind: "user_input"), options is empty and questions lists { id, header, question, options: [{ label, value }], allowCustomAnswer, multiSelect }.

Thread

GET /v1/threads/:hostId/:threadId

200 { "item": FeedItem, "messages": [Message], "canStop": true }
Message { "id": "...", "role": "assistant", "text": "...", "createdAt": "..." }

messages holds the last 20, oldest first, each trimmed to 2000 characters.

POST /v1/threads/:hostId/:threadId/messages
{ "text": "Yes, commit it" }
202

A message to a busy thread waits until the current turn ends. Nothing is interrupted.

POST /v1/threads/:hostId/:threadId/respond
{ "requestId": "...", "decision": "accept" }
or
{ "requestId": "...", "answers": { "<questionId>": "<value>" } }
202

Each answer is an option value or a typed answer. For a question with multiSelect: true, send an array of option values instead, for example { "<questionId>": ["sqlite", "postgres"] }.

POST /v1/threads/:hostId/:threadId/stop
202

POST /v1/threads/:hostId/:threadId/settle
202

Settles a thread, as in T3. A settled thread that finished or failed leaves the feed. To settle all of Recent, settle each item.

Thread detail fills request and via the same way as the feed when a subagent waits on you.

Summary

The counts behind the watch face complication. It reads no thread pages, so it is cheap to call.

GET /v1/summary

200 { "needsYou": 1, "working": 3, "hostsOffline": 0,
      "next": { "hostId": "...", "threadId": "...", "title": "Receipt OCR", "hostLabel": "Mac mini" } }

next is the thread that has waited longest for you, or null.

New thread

GET /v1/projects

200 { "hosts": [{ "id": "...", "label": "Mac mini", "status": "online", "error": null,
                   "projects": [{ "id": "...", "title": "wristcode", "model": "claude-opus-5-5" }] }] }

A project with "model": null has no default model, so the watch should not offer it.

POST /v1/threads
{ "hostId": "...", "projectId": "...", "text": "Add a complication for the waiting count" }

201 { "hostId": "...", "threadId": "..." }

The new thread uses the project's default model, or the host's, and the host's default runtime mode.

Notifications

The gateway pushes when a thread starts waiting for you, finishes, or fails. Each push has an aps.category and the custom keys hostId, threadId (absent on host pushes), and, for approvals and questions, requestId. A test push carries no custom keys. A subagent's push is titled with the thread that started it, its body starts with "Subagent