REST API

The Apple app and scripts use the routes under /v1. Read Overview first for authentication, errors, and limits.

Objects#

Account#

{
  "id": "acc_01jb2j0p8c",
  "created_at": 1760000000.0,
  "settings": { "live_activities": true }
}

Device#

{
  "id": "dev_3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "platform": "ios",
  "model": "iPhone18,1",
  "os_version": "27.0",
  "app_version": "1.0 (1)",
  "apns_environment": "production",
  "apns_token": "a1b2...",
  "push_to_start_token": "c3d4...",
  "widget_push_token": "e5f6...",
  "updated_at": 1760000000.0
}

Key#

{
  "id": "key_01jb2k3v9d",
  "label": "Claude Code",
  "prefix": "mck_a1b2",
  "last4": "x9Qz",
  "created_at": 1760000000.0,
  "last_used_at": 1760112300.9,
  "last_client": { "name": "claude-code", "version": "2.1.290" },
  "last_host": "studio-mac",
  "counts": { "todo": 3, "in_progress": 1, "done": 12, "cancelled": 0 }
}

• last_client is the MCP clientInfo of the most recent MCP request. It is null until an MCP client uses the key.
• last_host is the most recent host name that a request of the key sent. It is null until a request sends one.
• last_used_at changes one time in one minute at most.

Task#

{
  "id": "tsk_01jb2m9x4e7q",
  "key_id": "key_01jb2k3v9d",
  "title": "Add dark mode support",
  "description": "Implement a dark theme in all views.",
  "status": "in_progress",
  "priority": "high",
  "notify": true,
  "progress": 40,
  "status_note": "Updating the color tokens",
  "source": "agent",
  "created_at": 1760112000.412,
  "updated_at": 1760112300.9,
  "completed_at": null,
  "seen_at": 1760112010.2,
  "host": "studio-mac"
}

A task from before the fields seen_at and host does not have them in its JSON until its next change. Read a missing field as null.

Question#

{
  "id": "qst_01jb2n4r8t",
  "key_id": "key_01jb2k3v9d",
  "task_id": "tsk_01jb2m9x4e7q",
  "prompt": "Deploy to production now?",
  "kind": "confirm",
  "options": ["Yes", "No"],
  "status": "pending",
  "answer": null,
  "created_at": 1760112400.0,
  "answered_at": null,
  "expires_at": 1760116000.0
}

A question leaves pending one time, and does not change after that.

Accounts#

POST /v1/accounts has a strict rate limit for each IP address. A server that uses App Attest needs an attestation in the body, from POST /v1/attest/challenge. See App integrity.

Devices#

The body of PUT has the fields of the Device without id and updated_at. The three tokens are optional.

• A token that is not in the body is null. Send all tokens that the device has in each PUT.
• The response repeats the stored fields and adds id and updated_at.
• One APNs token belongs to one device registration. If a PUT has an apns_token that an older registration has (for example after the app is installed again), the server sets all tokens of the older registration to null.
• If APNs reports that a token is not valid (410, or BadDeviceToken), the server sets that token to null.

Keys#

A deleted key, or a deleted account, is unusable when the response comes: its credential is refused, and no route returns its data. The server removes the data itself in small steps after that, and finishes a deletion that stopped.

Tasks#

Both credential types can use these routes. An API key is limited to its own tasks.

List tasks#

Tasks are sorted by updated_at, newest first. Continue to the next page while next_cursor is not null. If priority is set, a page can have fewer tasks than limit, or no tasks, and can still have a next_cursor.

Create a task#

Only title is necessary.

{
  "key_id": "key_01jb2k3v9d",
  "title": "Write unit tests",
  "description": "",
  "status": "todo",
  "priority": "medium",
  "notify": true
}

Update a task#

PATCH accepts any subset of title, description, status, priority, notify, progress, status_note.

• A field that is not in the body does not change.
• progress and status_note accept null. The other fields do not.
• If status becomes done, the server sets progress to 100.
• A PATCH that changes no field returns the task as it is. updated_at stays the same, and the server sends no event and no push.

Questions#

List questions#

GET /v1/questions returns the newest questions first, 100 at most. The query parameter status has one status, or several with commas between them. The default is pending.

Ask a question#

Only prompt is necessary.

{
  "prompt": "Which environment?",
  "kind": "choice",
  "options": ["Staging", "Production"],
  "task_id": "tsk_01jb2m9x4e7q",
  "expires_in": 3600
}

A key can have 20 pending questions. One more gives 409.

Wait for the answer#

GET /v1/questions/{question_id}?wait=30 holds the request until the status is not pending, for 30 seconds at most. wait is 0 to 50 seconds. The default is 0.

• The response is the Question in each case. Look at status.
• If expires_at comes before the end of the wait, the request returns at that time with the status expired.
• If the result is still pending, send the request again.
• A key can have 32 requests that wait at the same time on one server process, over this route and GET /v1/inbox?wait=. One more gets 429 with Retry-After. A request with wait=0 is not counted.

Answer a question#

If two answers arrive at the same time, one gets 200 and the other gets 409.

Cancel a question#

DELETE gives 204 for a question that is pending or already cancelled. It gives 409 for a question that is answered or expired.

Inbox and messages#

When the person creates, changes, or deletes a task of a key with the account token, or answers a question, the server adds an item to the inbox of that key. See Inbox for the objects, the query parameters, and the rules.

Activity log#

The server keeps the last 200 requests of each API key for 7 days. The app shows them, so that the person can see what went wrong, copy an entry, and give it to the agent.

GET /v1/keys/{key_id}/activity returns the entries of one key of the account, newest first. A key of a different account gives 404. The log has no event on the event stream: get it when the person opens it.

Entry#

{
  "id": "act_01jb2q7m3k",
  "at": 1760112300.9,
  "surface": "mcp",
  "action": "update_task",
  "status": "error",
  "code": "not_found",
  "message": "Task not found.",
  "duration_ms": 4,
  "client": { "name": "claude-code", "version": "2.1.290" },
  "host": "studio-mac"
}

message is text that the server wrote, for example Task not found. For a request that is not valid, it has the names of the fields and not their values, for example Invalid fields: priority, title. A tool error has the same code that the REST API gives for that error.

What has an entry#

One request of an API key has one entry, also a request that failed and a request above the rate limit. These requests have no entry:

• A request with an account token, or with no valid credential.
• A request that the server refuses before it reads the credential: an unknown path, a REST body that is not JSON, or a body above the size limit.
• GET /health, the event stream, and the pages of the website.
• An MCP notification.
• A call that only waited: a read of the inbox with wait or wait_seconds that ended with no item, and a read of a question that is still pending after its wait. A call that waited and then got a result has one entry.

The server writes an entry after it sends the response. Thus an entry can be absent for a moment after its request.

What the log stores#

The log has only the fields of the Entry. It never has the text of a task, a question, an answer, a message, or a notification, and it never has a credential. The server deletes an entry after 7 days, keeps the newest 200 entries of a key, and deletes the log with its key and with the account.

Live Activities#

• The app calls PUT each time ActivityKit gives a new update token for the activity of that task.
• The task and the device must belong to the account, else the result is 404.
• DELETE gives 204 also when the device has no registered activity.
• The server removes the registrations of a task after it sends end.

See Push for the pushes that the server sends.