# Delete a note

`DELETE /notes/{note_uuid}`

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

Soft-delete a note. The note remains in the database for audit / compliance purposes
but is removed from list / show responses (a subsequent show or list call returns 404).

See the [Soft Deletion](/docs/guides/watcheye_api/soft-deletion) section of the API
guide for the full policy (30-day recovery window, portal-only restore).

If you need to keep the note accessible for compliance / audit purposes but no longer
want it surfaced in day-to-day workflows, prefer
[archiving](/docs/guides/watcheye_api/soft-deletion#prefer-archiving-over-deletion-for-compliance)
instead of deleting. Archiving a note is currently a portal-only action; the API
surfaces the resulting `archived_at` timestamp and lets you filter by it.
The deleted note record is returned in the response as confirmation.

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

* Notes authored by a portal user (`created_by.type` is `user`) return 404, mirroring
  the PATCH behaviour - portal-authored notes are managed through the portal.
* Notes with `is_immutable: true` return 403 because they record an audit-trail entry
  that no actor on any channel can remove.

Notes have no dependent records, so this is a single-record delete.

## Parameters

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

## Responses

### 200 Note deleted (soft-delete - returned as confirmation)

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