---
title: "Read Candor's weekly reviews, newest first."
method: GET
path: "/v1/reviews"
---

# Read Candor's weekly reviews, newest first.

`GET /v1/reviews`

## Request

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

Each review lists the areas worth the agent's attention and the gaps worth filling, with what it marked settled since the review before. An area carries its `id` within the review, `item_id` (the `review.area` item id that reviews.update takes as `area`), its title, topic (income, spending, cash, debt, savings, retirement, tax, protection, housing, family, estate, goals, business, investing, work, other), kind (problem, opportunity, question), what was noticed, why it matters, what is unknown, `since_last_review` (new, unchanged, updated), `outcome` once the agent or the person recorded one (`state` looked_into or set_aside, `by` agent or person, `on`, and `found`), and `refs`, the records behind it. Areas state no figures; the records do. A gap carries what to settle, which area it changes, what to check or ask, and `record_as` (rule_on_the_payee, note_on_the_record, note, connect_the_account, goal). The latest review is also in the opening. Records and pagination live under `data.page`.

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

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