List attention items

GET

/api/attention-items

• Production

Returns all attention items for the tenant. Attention items are created automatically when the AI needs human intervention — for example, when reply validation fails, when a customer requests a human agent, or when the AI detects a sensitive situation it cannot handle. Use this endpoint to build a queue of items requiring human review.

Authorizations

• bearerAuth

Responses

200

List of attention items, including both open and resolved items. Filter client-side by status if needed. An API key restricted to a brand or workspace receives the items of the workspaces its restriction covers.

List of attention items requiring human review.

Array<object>

An attention item flags a conversation that needs human review. These are created automatically when the AI is unable to handle a situation — for example, when reply validation fails after 3 attempts, when a customer explicitly requests a human agent, or when the AI detects a sensitive situation it cannot handle.

object

id

required

Unique identifier for the attention item.

string format: uuid

Example

ai1a2b3c-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this attention item belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

conversationId

required

The conversation that triggered this attention item.

string format: uuid

Example

c1a2b3c4-5678-9abc-def0-1234567890ab

type

required

The category of attention required. Common values: ‘validation_failed’ (AI reply failed fact-checking), ‘human_requested’ (customer asked for a human), ‘escalation’ (AI detected a sensitive issue).

string

Example

validation_failed

reason

Detailed explanation of why the attention item was created.

string | null

Example

Reply validation failed after 3 attempts. The AI was unable to verify pricing information against the knowledge base.

status

required

Current status of the attention item. ‘open’ means unresolved, ‘resolved’ means a human has reviewed and addressed it.

string

Example

open

createdAt

required

Timestamp when the attention item was created.

string format: date-time

Example

2026-03-25T11:42:00.000Z

resolvedAt

Timestamp when the attention item was resolved. Null while still open.

string | null format: date-time

400

A conversationId filter that is not an id, or, from an API key not restricted to a brand or workspace, a workspaceId filter that is not an id (Invalid filter).

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]