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

# Human attention

> Use the durable human attention contract when an agent execution needs a human decision, answer, access grant, or approval.

Human attention pauses one agent execution at `needs_human` and records the
information a human needs to act. The request and execution transition are
atomic. Generic execution transitions cannot enter or leave `needs_human`.

## Endpoints

| Method | Endpoint                                              | Purpose                                                |
| ------ | ----------------------------------------------------- | ------------------------------------------------------ |
| `GET`  | `/api/orgs/{id}/attention`                            | List relevant open or closed items                     |
| `POST` | `/api/orgs/{id}/attention`                            | Request attention for an execution                     |
| `GET`  | `/api/orgs/{id}/attention/{attentionId}`              | Read one detail projection                             |
| `POST` | `/api/orgs/{id}/attention/{attentionId}/resolve`      | Resolve for an eligible human                          |
| `POST` | `/api/orgs/{id}/attention/{attentionId}/cancel`       | Cancel as the requesting agent                         |
| `POST` | `/api/orgs/{id}/attention/{attentionId}/admin-cancel` | Cancel as an authorized human administrator            |
| `POST` | `/api/orgs/{id}/attention/{attentionId}/retarget`     | Change the target as an authorized human administrator |

Create requests require an execution ID, expected execution state version,
kind, bounded text fields, one exact target, and an idempotency key. Targets
are a member, team, or project administrators. Resolve, cancel, and retarget
requests include both expected versions. Reuse of an idempotency key with the
same input returns the original result; a different input returns `409`.

## Lifecycle

The create operation moves the execution to `needs_human` and creates one open
attention item. Resolve and cancel close the item and move the execution to
`waiting`. Approval and destructive-action items accept `approved` or
`rejected`; access items accept `provided` or `denied`; clarification,
decision, and other items require an `answered` outcome with a summary.

`mode=recovery` lists open items whose original target is no longer eligible
and is available only to authorized human administrators. Stale versions,
invalid lifecycle edges, and ineligible targets return stable `409` errors.
Request text is bounded and rejects secret-like content. Public responses
contain current and immutable actor/target snapshots, execution state, issue,
and project context. They omit provenance, hashes, prompts, logs, credentials,
and local paths.

See the [endpoint reference](/api-reference/endpoints) and [field reference](/api-reference/fields) for the complete REST contract.