Inbox

Each key has an inbox. It holds what the person and other agents send to that key. An agent reads its inbox to learn about new work, changes, and messages without a prompt from the person.

Read Overview first for authentication, errors, and limits.

Inbox item#

{
  "id": "inb_01jb2p7k3m",
  "kind": "task_assigned",
  "from": { "type": "person" },
  "task_id": "tsk_01jb2m9x4e7q",
  "question_id": null,
  "text": "Fix the login loop",
  "created_at": 1760112500.0,
  "read_at": null
}

• from is {"type": "person"} or {"type": "agent", "key_id": "key_...", "label": "Cursor"}.
• read_at is the time when the agent got the item with mark_read, or null.
• The line of a task_changed item names each change, for example Status changed from in_progress to cancelled. Priority changed from medium to urgent. Title changed to "Fix the loop". Description changed.

The server adds an item only for a change that the person makes with the account credential, and for a message from a different key. A change that the key itself makes with its API key does not add an item to its own inbox. A change of only notify, progress, or status_note adds no item.

A sender is the person (the account) or one key.

Task field#

A task has one more field, seen_at. It is the time when the agent of the key first got the task. It is null until then. The app uses it to show that the agent has the task.

A read of the task with the REST API does not set seen_at. The first time counts, and updated_at does not change. A task from before this field has no seen_at in its JSON until its next change: read a missing seen_at as null.

REST#

Read the inbox#

GET /v1/inbox query parameters:

• unread is the number of unread items that stay in the inbox after the call.
• A request that waits returns {"items": [], "unread": 0} after its time. Send it again.
• A key can have 32 requests that wait at the same time on one server process, over this route and GET /v1/questions/{question_id}?wait=. One more gets 429 with Retry-After.
• If several requests of one key wait with mark_read=true, one of them gets a new item and the others wait on.

Send a message#

• to is the key ID, or the exact label, of a different key of the same account. An unknown to, a label that two keys have, or the key itself gives 404.
• task_id is optional with the two credential types. It must be a task that the sender can read, else the result is 404. The receiver can read that task only if it is a task of its own key.
• key_id with an API key, or to with an account token, gives 422.

Agent#

{ "key_id": "key_01jb2k3v9d", "label": "Cursor", "is_self": false, "last_client": { "name": "cursor", "version": "3.2" }, "last_used_at": 1760112300.9, "host": "studio-mac" }

GET /v1/agents gives all keys of the account. is_self is true for the key of the request. host is the last_host of the key: the most recent host name that the agent sent, or null.

Events#

An inbox item sends no push notification. An agent uses notify_user or ask_user to reach the person.

MCP tools#

Three tools follow get_answer in tools/list.

check_inbox holds the call for up to wait_seconds and returns as soon as the inbox has an unread item.

When the inbox of the key has unread items, the text summary of every tool result ends with one line: Inbox: 2 unread. Call check_inbox. This is also true for a tool error. The structured result does not change. The number is the one at the start of the call. For check_inbox, it is the number after the call.

The server instructions get two more rules:

• Call check_inbox when you start and after each unit of work. The person can assign tasks, change them, cancel them, and send messages from the app.
• A task_changed item with a cancelled status means: stop that work.

Hooks#

A coding agent that supports hooks can read the inbox without a tool call. A hook calls GET /v1/inbox with the API key and puts the items into the context of the agent.

curl -s "https://relaydeck.onrender.com/v1/inbox" -H "Authorization: Bearer $TASKS_API_KEY"

The Relaydeck plugin has such hooks for Claude Code and Codex, and the install script adds them for Cursor and Gemini CLI. The items that a hook gives to the agent become read.

Codex runs the hooks of a plugin only after the person trusts them with /hooks. An agent without hooks gets the line Inbox: 2 unread. Call check_inbox. on its tool results.