---
title: "Create a stable Markdown note with optional resource and revisit time."
method: POST
path: "/v1/notes"
---

# Create a stable Markdown note with optional resource and revisit time.

`POST /v1/notes`

## Request

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

Create a stable Markdown note with optional resource and revisit time.

## Headers

- `Idempotency-Key` string, required

## Request body

- NoteCreateRequest: Remember context, user statements, findings, decisions, or open questions and return the saved note. Resource links and revisit dates are optional. This does not change a linked financial record or authorize external action. Ordinary working notes need no context-topic tags; tag durable user context, including a household fact that `open` lists in context_needed and you inferred from the records.
  - `body_markdown` string, required: Complete Markdown body. Keep observed facts separate from assumptions; for unfinished work, preserve the baseline and enough context to check the outcome on revisit. Use exact record ids when referring to evidence.
  - `context_topics` ContextTopic[]: Tags this active note as durable workspace context for the listed standard topics, so future agents receive it directly from `open`. Use for durable user context, meaning something the user said or a household fact that `open` lists in context_needed which you inferred from the records, stated as your inference with its evidence. Omit it for ordinary working or re-check notes.
  - `about` NoteAbout: Links the note to the exact record it is about, so a later run can find it from the record instead of by searching note text.
    - `resource` string, required: Resource name, such as transactions or accounts.
    - `id` string, required: Canonical id of that record, pasted whole.
  - `revisit_at` union: When to surface this note as due in a future workspace opening, as a date (YYYY-MM-DD, read as noon UTC) or an ISO 8601 time. Omit it to keep the note retrievable without due-time resurfacing. This does not schedule an agent run or notify the user; background monitoring uses the host scheduler.
    - string, date-time
    - string, date
  - `watch` union: Something Candor watches for in the records for this note, so the opening says what it came to without you searching. Only transactions that reach the records after the watch is set count. A payee watch reports watch.seen or watch.broken when one posts, or watch.missed or watch.held once revisit_at passes without one (a promised refund, a cancelled charge, an expected payment). A balance watch reports watch.crossed while the account holds less than the floor (a low-balance alert). An amount watch reports watch.seen for any transaction at or over the amount (a large-charge alert).
    - object
      - `payee` string, required: The payee as the transactions name it (merchant or description), matched without regard to case.
      - `expect` 'charge' | 'deposit' | 'no_charge', required: charge or deposit is answered when one posts; no_charge holds while none posts and breaks if one does.
    - object
      - `account_id` string, required: The account to watch, as accounts list gives it.
      - `balance_below` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range.
        - string
        - string
        - string
    - object
      - `amount_over` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range.
        - string
        - string
        - string
      - `direction` 'inflow' | 'outflow'

## Response `200`

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