---
title: "Update a note in place without changing its id."
method: POST
path: "/v1/notes/update"
---

# Update a note in place without changing its id.

`POST /v1/notes/update`

## Request

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

Update a note in place without changing its id.

## Headers

- `Idempotency-Key` string, required

## Request body

- union: Update the same note and return its saved state. Supply at least one changed field; omitted fields preserve their current values. Resolve the note separately when its context is no longer current or its open question is settled.
  - object
    - `note_id` string, required: The note this concerns.
    - `body_markdown` string, required: Replaces the entire Markdown body, not an appended fragment. Omit it to preserve the current body; null and empty text are rejected. Carry forward any context still needed.
    - `context_topics` ContextTopic[]: Replaces the note's standard context topics. An empty array returns it to an ordinary note; omitting the field preserves its current topics.
    - `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: Replace the revisit time, as a date (YYYY-MM-DD) or an ISO 8601 time. Omit it to preserve the current time; null clears it and stops due-time resurfacing. This does not schedule an agent run or notify the user.
      - 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'
  - object
    - `note_id` string, required: The note this concerns.
    - `body_markdown` string: Replaces the entire Markdown body, not an appended fragment. Omit it to preserve the current body; null and empty text are rejected. Carry forward any context still needed.
    - `context_topics` ContextTopic[]: Replaces the note's standard context topics. An empty array returns it to an ordinary note; omitting the field preserves its current topics.
    - `about` NoteAbout, required: 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: Replace the revisit time, as a date (YYYY-MM-DD) or an ISO 8601 time. Omit it to preserve the current time; null clears it and stops due-time resurfacing. This does not schedule an agent run or notify the user.
      - 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'
  - object
    - `note_id` string, required: The note this concerns.
    - `body_markdown` string: Replaces the entire Markdown body, not an appended fragment. Omit it to preserve the current body; null and empty text are rejected. Carry forward any context still needed.
    - `context_topics` ContextTopic[]: Replaces the note's standard context topics. An empty array returns it to an ordinary note; omitting the field preserves its current topics.
    - `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, required: Replace the revisit time, as a date (YYYY-MM-DD) or an ISO 8601 time. Omit it to preserve the current time; null clears it and stops due-time resurfacing. This does not schedule an agent run or notify the user.
      - 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'
  - object
    - `note_id` string, required: The note this concerns.
    - `body_markdown` string: Replaces the entire Markdown body, not an appended fragment. Omit it to preserve the current body; null and empty text are rejected. Carry forward any context still needed.
    - `context_topics` ContextTopic[], required: Replaces the note's standard context topics. An empty array returns it to an ordinary note; omitting the field preserves its current topics.
    - `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: Replace the revisit time, as a date (YYYY-MM-DD) or an ISO 8601 time. Omit it to preserve the current time; null clears it and stops due-time resurfacing. This does not schedule an agent run or notify the user.
      - 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'
  - object
    - `note_id` string, required: The note this concerns.
    - `body_markdown` string: Replaces the entire Markdown body, not an appended fragment. Omit it to preserve the current body; null and empty text are rejected. Carry forward any context still needed.
    - `context_topics` ContextTopic[]: Replaces the note's standard context topics. An empty array returns it to an ordinary note; omitting the field preserves its current topics.
    - `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: Replace the revisit time, as a date (YYYY-MM-DD) or an ISO 8601 time. Omit it to preserve the current time; null clears it and stops due-time resurfacing. This does not schedule an agent run or notify the user.
      - string, date-time
      - string, date
    - `watch` union, required: 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`

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