> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tylon.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbox

> Read what is waiting for a person in Tylon — branch suggestions, refused promotions, grouped errors — and clear it.

The queue of decisions a machine could not make. It is never a copy of
state, which is what makes it the honest thing to alert on: an inbox that is
empty means nothing is waiting on a human.

## What is waiting

<ParamField path="GET /v1/inbox" type="endpoint" />

What is waiting for a person to decide.

<ParamField query="projectId" type="string">
  Which product. Optional when the board has one project.
</ParamField>

Twelve kinds turn up here, and `kind` says which. The list is the product's
own — these are the labels the screen shows.

| `kind`                   |                                             |
| ------------------------ | ------------------------------------------- |
| `promotion_blocked`      | Promotion refused                           |
| `branch_suggestion`      | Branch created outside Tylon                |
| `branch_deleted`         | Linked branch is gone                       |
| `pr_merged_outside`      | Merged outside Tylon                        |
| `pr_closed_outside`      | PR closed on the provider                   |
| `waiting_stale`          | Waiting for a long time                     |
| `error_reported`         | Broke in production                         |
| `connection_broken`      | A connection needs reconnecting             |
| `backmerge_open`         | A hotfix has not made it back               |
| `agent_gave_up`          | An agent could not finish                   |
| `proposal_waiting`       | An agent offered a change                   |
| `agent_stopped_reacting` | An agent stopped answering its pull request |

`detail` carries why, in the provider's words when the provider gave them.

<Note>
  Most of these are **derived**, not stored — they are read from the state
  they describe, so they go when it does. Only `branch_suggestion`,
  `branch_deleted` and `error_reported` are rows, and only those can be
  dismissed; the rest clear themselves when the thing they are about is dealt
  with.
</Note>

## Clearing it

<ParamField path="POST /v1/inbox/{itemId}/adopt" type="endpoint" />

Take a branch somebody cut in a terminal and make it the card's.

<ParamField query="card" type="integer">
  Which card. Optional — the Inbox already guessed from the naming
  convention, and this is how you overrule the guess.
</ParamField>

<ParamField path="DELETE /v1/inbox/{itemId}" type="endpoint" />

Put the item away without acting on it. Both answer `204`.