# Update a note

`PATCH /notes/{note_uuid}`

- Base: `PATCH https://portal.watcheye.com.au/api/v1/notes/{note_uuid}`

Update a note's text. Only `note_text` can be changed - the note's parent entity, parent
event, author and archive state are all immutable from the API. To "move" a note to a
different entity or event, delete it and re-create.

Only notes authored by an API key on this account can be updated through this endpoint:

* Notes authored by a portal user (`created_by.type` is `user`) return 404 from this
  endpoint, even if the note exists - it can only be edited via the portal by its author
  or an account manager.
* Notes with `is_immutable: true` (for example, the per-event audit-trail note left by a
  bulk update) return 403 because no actor on any channel can modify them.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `note_uuid` | path | string (uuid) | **Required.** The note UUID |

## Request body

The fields to update

| Field | Type | Description |
|-------|------|-------------|
| `note_text` | string [max 5000 characters] | **Required.** Replacement text for the note. Max 5000 characters. Example: `Updated - customer's identity has now been independently verified.` |

**Sample request**

```json
{
    "note_text": "Updated - customer's identity has now been independently verified."
}
```

## Responses

### 200 Note updated

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | object | A note attached to an entity, optionally also linked to an event. Deleting a note is a soft-delete: the record stays in the database for audit / compliance purposes but is no longer surfaced by the API. Subsequent show or list calls for a deleted note return `404`. Notes can be archived in the portal (the `archived_at` timestamp); the API surfaces this state for filtering but archive/unarchive operations are not currently exposed via the API. |
| `data.uuid` | string (uuid) | The note's UUID Example: `7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data.note_number` | string | A short obfuscated public identifier for the note (e.g. "N-A1-B2C-3D4") Example: `N-A1-B2C-3D4` |
| `data.note_text` | string | The free-text content of the note (max 5000 characters) Example: `Confirmed match against verified passport details.` |
| `data.created_by` | object or null | Identifies who created the note. The `type` discriminator picks the shape of the remaining fields: * `{ type: "user", uuid, username }` - a portal user created the note. The portal user (or an account manager) can edit/delete it through the portal. The API cannot edit or delete user-authored notes. * `{ type: "api_key", uuid, label }` - an API key on this account created the note. The API can manage these notes via the PATCH and DELETE endpoints. The portal cannot edit or delete API-key-authored notes. * `null` - rare legacy notes from before actor attribution was recorded; treat as read-only. |
| `data.created_by.type` | string | Discriminator for the actor type. Enum: `user`, `api_key` |
| `data.created_by.uuid` | string (uuid) | UUID of the user or API key that created the note. |
| `data.created_by.username` | string | Username of the portal user. Present only when `type` is `user`. |
| `data.created_by.label` | string | Label of the API key. Present only when `type` is `api_key`. |
| `data.is_immutable` | boolean | When true, the note is an immutable audit-trail entry and cannot be edited or deleted by any actor through any channel. PATCH and DELETE requests against an immutable note return 403. Example: `false` |
| `data.entity_uuid` | string (uuid) | UUID of the entity this note is attached to |
| `data.program_uuid` | string (uuid) | UUID of the program the entity belongs to |
| `data.event_uuid` | string (uuid) or null | UUID of the event this note is attached to, if any. Notes created via the [Events PATCH](/docs/reference/event.update) endpoint with a `note` field carry an `event_uuid`; notes created via [POST /v1/entities/{uuid}/notes](/docs/reference/note.create) do not. |
| `data.archived_at` | string (date-time) or null | ISO 8601 timestamp at which the note was archived in the portal (null if not archived) |
| `data.created_at` | string (date-time) | Example: `2025-01-01T00:00:00Z` |
| `data.updated_at` | string (date-time) | Example: `2025-01-01T00:00:00Z` |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": {
        "uuid": "7c1c0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
        "note_number": "N-A1-B2C-3D4",
        "note_text": "Confirmed match against verified passport details.",
        "created_by": {
            "type": "user",
            "uuid": "00000000-0000-0000-0000-000000000000",
            "username": "string",
            "label": "string"
        },
        "is_immutable": false,
        "entity_uuid": "00000000-0000-0000-0000-000000000000",
        "program_uuid": "00000000-0000-0000-0000-000000000000",
        "event_uuid": "00000000-0000-0000-0000-000000000000",
        "archived_at": "2024-01-01T00:00:00Z",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 400, 401, 403, 404, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))