---
title: "Retired. Refuses with attention_retired."
method: POST
path: "/v1/attention/update"
deprecated: true
---

# Retired. Refuses with attention_retired.

`POST /v1/attention/update`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/attention/update`
- Auth: HTTP bearer

> **Deprecated.**

Attention decisions retired with the attention engine. A body that does not match the schema is refused for its fields; any other request refuses with `attention_retired` and offers the opening, reviews.update, and a note about the record.

## Headers

- `Idempotency-Key` string, required

## Request body

- AttentionUpdateRequest: Retired: attention.update refuses with attention_retired. The user's decision about one attention situation, recorded on their word, or the question the agent asked them about it. Deferring, dismissing, and settling require the user's reason, confirming requires what shows it holds, and asking requires the question; deferring also requires `revisit_at`.
  - `situation_id` string, required: The situation's `id` from attention.list, conversations.get, or an opening's attention item. A decision on a folded situation covers its whole card.
  - `state` 'deferred' | 'dismissed' | 'settled' | 'confirmed' | 'asked' | 'active', required: `deferred` sets it aside until `revisit_at`. `dismissed` holds it until it grows. `settled` marks it handled. `confirmed` records what shows it holds for this household, from the records, notes, or the user's answer; the user's dashboard states a finding only once it is confirmed. `asked` records the question you put to the user about something only they can tell; it stays on the list and their dashboard holds it until a later decision. `active` restores it from any earlier decision.
  - `reason` string: The user's words for the decision, such as "Starting estimated payments in January", or your question for `asked`. Required except to restore. The review never reads it.
  - `revisit_at` union: When a deferred situation returns, still ahead, as a date (YYYY-MM-DD, read as noon UTC) or an ISO 8601 time. Required for `deferred` and accepted only then.
    - string, date-time
    - string, date
  - `note_id` string: A context note in this workspace that keeps what the reason says about the household, linked to the decision.

## Response `200`

Not returned; every request refuses with attention_retired.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

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