---
title: "Questions your agents are waiting on you for, or your settled history"
method: GET
path: "/notices"
tags: ["Notices"]
---

# Questions your agents are waiting on you for, or your settled history

`GET /notices`

## Request

- Base URL: `https://api.atako.ai`
- URL: `https://api.atako.ai/notices`
- Auth: HTTP bearer

Two sorts, never mixed on the same page. The default — `state=open` (or omitted), no `order` — is the queue sorted the way the Floor shows it: priority descending, then kind rank (blocker, guardrail, choice, info), then oldest first; a plain `limit`, `nextCursor` always `null` (AF-52: this order is fixed, never paginated). Any other `state` (`answered`, `expired`, `withdrawn`, `settled`, `all`), or `order=recent` on `open`, switches to the HISTORY sort instead: most recently settled first (answered date if answered, else created date), paginated by the opaque `cursor` — pass back a page's `nextCursor` as the next call's `cursor` until it comes back `null`. `settled` means any of the three non-open states at once (answered, expired or withdrawn) — use it for a history view that must never show a still-open notice; `all` keeps open notices mixed in, for a combined per-person journal.

A company admin may read a colleague's queue/history with `recipientUserId`, or the whole company's, line by line, with `scope=company` (the two are mutually exclusive) — anyone else passing either gets 403, never a silently empty list. Notices past their `expiresAt` flip to `expired` on read, so this list never shows a stale question.

## Query parameters

- `state` 'open' | 'answered' | 'expired' | 'withdrawn' | 'settled' | 'all'
- `kind` 'blocker' | 'guardrail' | 'choice' | 'info'
- `priority` 'critical' | 'high' | 'normal' | 'low'
- `agentId` string, uuid
- `conversationId` string, uuid
- `originKind` 'chat' | 'cron' | 'email' | 'webhook' | 'interagent' | 'subagent'
- `recipientUserId` string, uuid
- `scope` 'mine' | 'company'
- `order` 'recent'
- `cursor` string
- `limit` integer

## Response `200`

- NoticeList: `nextCursor` is only meaningful on the history sort (a settled `state`, `all`, or `order=recent`) — pass it back as `?cursor=` for the next page. It is always `null` on the default open queue (AF-52): that sort is a plain `limit`, never paginated.
  - `notices` Notice[], required
    - `id` string, uuid, required
    - `agentId` string, uuid, required
    - `agentName` string, required
    - `recipientUserId` string, uuid, required
    - `recipientName` string
    - `kind` 'blocker' | 'guardrail' | 'choice' | 'info', required: Blocked / permission asked / arbitration / information. The first three are blocking: the agent waits.
    - `priority` 'critical' | 'high' | 'normal' | 'low', required
    - `subject` string, required: Short, stable — the deduplication key is derived from it, together with the origin: the same subject raised from two different sessions is two questions.
    - `question` string, required
    - `options` NoticeOption[], required
      - `id` string, required: Answer id — what you send back in `POST /notices/{id}/respond`.
      - `label` string, required
      - `tone` 'ok' | 'warn' | 'bad' | 'quiet': Suggested button colour.
      - `free` boolean: When true, this option opens a free-text field and `text` becomes required on respond.
    - `state` 'open' | 'answered' | 'expired' | 'withdrawn', required
    - `createdAt` string, date-time, required
    - `answeredAt` string, date-time, nullable
    - `expiresAt` string, date-time, nullable
    - `settledAt` string, date-time, required: `answeredAt` if answered, else `createdAt` — always set, including on an open notice. The one reliable date to show on a settled notice with no answer (`expired`/`withdrawn`).
    - `origin` NoticeOrigin: Where the question came from — the work object that raised it. Declared by the agent when it raises the notice, never guessed server-side. `null` on a notice raised before origins existed.
      - `kind` 'chat' | 'cron' | 'email' | 'webhook' | 'interagent' | 'subagent', required
      - `conversationId` string, uuid, nullable, required: The chat session, for `chat` origins only. This is what the session deep link carries.
      - `refId` string, nullable, required: The object id (always a uuid) for the five other kinds: email threadId, webhook endpointId, interagent contextId, cron job, sub-agent. `null` when the declared id resolves to nothing — a cron/sub-agent id is resolved against the agent's own rows (a raw Hermes job id or a sub-agent engine id is accepted and mapped to its Atako uuid).
      - `label` string, nullable, required: Human-readable name of that object (session title, thread subject, job title). `null` when it has none or has since been deleted — the link still works, it just shows the kind.
    - `answer` NoticeAnswer: The human decision, once made. `respondedByName` is frozen at answer time so the decision stays readable after the account is gone.
      - `chosenOption` string, nullable, required
      - `freeText` string, nullable
      - `respondedBy` string, uuid, nullable
      - `respondedByName` string, nullable
      - `createdAt` string, date-time, required
  - `nextCursor` string, nullable, required: Opaque cursor for the next history page, null once exhausted (or not applicable).

## Other responses

- `400`: Invalid query parameters, or an invalid cursor.
- `401`: Missing, malformed, or invalid bearer token / API key, or revoked session (SESSION_REVOKED).
- `403`: `recipientUserId`/`scope=company` given by a non-admin, or for a user outside your company.
- `404`: You belong to no company.

---

[API](https://skmtc.dev/atako/apis/atako-api.md) · [All operations](https://skmtc.dev/atako/apis/atako-api/llms.txt) · [OpenAPI document](https://skmtc.dev/atako/apis/atako-api/revisions/aa555c56fbd7?raw)