---
title: "Record what came of a weekly review area."
method: POST
path: "/v1/reviews/update"
---

# Record what came of a weekly review area.

`POST /v1/reviews/update`

## Request

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

Records that the agent looked into an area of Candor's weekly review, with what the records or the person showed, or that it is set aside, with why it does not apply. `area` is the `review.area` item's id from the opening. The person sees the outcome on the dashboard, the area leaves the opening, and the next review reads it. Recording again replaces the outcome. Returns the area as saved.

## Headers

- `Idempotency-Key` string, required

## Request body

- ReviewsUpdateRequest: What came of one area of Candor's weekly review.
  - `area` string, required: The review.area item's id from the opening.
  - `outcome` 'looked_into' | 'set_aside', required: `looked_into` with what the records or the person showed; `set_aside` with why it does not apply.
  - `found` string, required: What the records or the person showed, or why it does not apply, in plain words. The person reads it on the dashboard.

## Response `200`

Saved area envelope.

- 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)