---
title: "update_day_note"
description: "Update day note: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/update_day_note
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# update_day_note

Adds, replaces, or clears the user's one note for a calendar date. A day note is the user's one note about a whole calendar date (for example "Travel day" or "Sick"). It is not an Occurrence note, has no status, and never changes Completed, Not Completed, Unresolved, Needs decision, adherence, or reminders. Use update_occurrence_note for one scheduled instance and set_occurrence_status for Completed or Not Completed. Future dates are allowed.

## Permission and annotations

Required scope: `cadence.occurrences.write`. Contract 1.7.0; available since 1.1.0.

- `title`: "Update day note"
- `readOnlyHint`: false
- `destructiveHint`: true
- `idempotentHint`: true
- `openWorldHint`: false

Replaces the previous day note text, which Cadence does not keep in history, so destructiveHint is true under both Claude's and OpenAI's guidance. The same arguments produce the same day note, so idempotentHint is true. openWorldHint is false.

## Input

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` local_date ` | yes | string | Calendar date the note is about, in the account timezone.; format: ` date ` |
| ` note ` | yes | string | Day note text. An empty string clears the day note.; maxLength: ` 2000 `; pattern: <code>&#94;&#91;&#94;&#92;&#117;&#48;&#48;&#48;&#48;&#45;&#92;&#117;&#48;&#48;&#48;&#56;&#92;&#117;&#48;&#48;&#48;&#98;&#92;&#117;&#48;&#48;&#48;&#99;&#92;&#117;&#48;&#48;&#48;&#101;&#45;&#92;&#117;&#48;&#48;&#49;&#102;&#92;&#117;&#48;&#48;&#55;&#102;&#93;&#42;&#36;</code> |
| ` expected_revision ` | no | string | Revision the client last read. If the day note changed since, or does not exist, the call fails with `conflict`.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` idempotency_key ` | no | string | Optional client-chosen key. Repeating a call with the same key and input within 24 hours returns the first result and changes nothing.; minLength: ` 8 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |

## Output

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` day_note ` | yes | object or null | Null when the date never had a note and the request cleared it. |
| ` day_note.id ` | yes | string | format: ` uuid ` |
| ` day_note.local_date ` | yes | string | Calendar date (YYYY-MM-DD) in the account timezone.; format: ` date ` |
| ` day_note.note ` | yes | string or null | Day note text. Null after the user cleared it. |
| ` day_note.revision ` | yes | string | Opaque version token of this record. Send it back as `expected_revision` to avoid overwriting a newer change.; minLength: ` 1 `; maxLength: ` 128 `; pattern: ` ^[A-Za-z0-9._:-]+$ ` |
| ` day_note.updated_at ` | yes | string | format: ` date-time `; pattern: ` [Zz]$ ` |
| ` changed ` | yes | boolean | False when the day note already had this text. |

## Example call

Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.

```json
{
  "name": "update_day_note",
  "arguments": {
    "local_date": "2026-03-08",
    "note": "Travel day.\nSlept badly.",
    "expected_revision": "2026-03-08T07:30:00Z",
    "idempotency_key": "day-note-0001"
  }
}
```

## Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

```json
{
  "local_date": "2026-03-08",
  "day_note": {
    "id": "00000006-1111-4111-8111-000000000006",
    "local_date": "2026-03-08",
    "note": "Travel day",
    "revision": "2026-03-08T07:30:00Z",
    "updated_at": "2026-03-08T07:30:00Z"
  },
  "changed": true
}
```

## Errors

- `invalid_input`: The input does not match the tool's schema or rules. `field_errors` names each problem.
- `authentication_required`: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
- `rate_limited`: Too many requests for this connection. Retry after `retry_after_seconds`.
- `service_unavailable`: Cadence integrations are temporarily unavailable.
- `internal_error`: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`.
- `insufficient_scope`: The connection does not include the permission this tool needs. `required_scopes` lists it.
- `conflict`: The record changed since it was read: `expected_status` or `expected_revision` is stale. Nothing changed.
- `idempotency_key_reused`: The `idempotency_key` was already used with a different input. Use a new key for a new request.

Output size limits can also return `limit_exceeded`. See [error handling](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
