# Create a note on an entity

`POST /entities/{entity_uuid}/notes`

- Base: `POST https://portal.watcheye.com.au/api/v1/entities/{entity_uuid}/notes`

Create a new note attached to the specified entity. The note inherits the entity's
program and account.

Notes created via this endpoint are attributed to the calling API key (the response
`created_by` carries `{ type: "api_key", uuid, label }`). They cannot be edited or
deleted from the portal. Any API key on the same account can manage these notes via the
[PATCH](/docs/reference/note.update) and [DELETE](/docs/reference/note.delete) endpoints.

To attach a note to an event (rather than just to the entity) use the
[Events PATCH](/docs/reference/event.update) endpoint with a `note` field.

## Idempotency

This endpoint accepts the `Idempotency-Key` header so that retries on network failure are
safe. See the [Idempotency](/docs/guides/watcheye_api/idempotency) section of the
API guide for the full contract.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `entity_uuid` | path | string (uuid) | **Required.** The entity UUID |
| `Idempotency-Key` | header | string [max 255 characters] | Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the [Idempotency](/docs/guides/watcheye_api/idempotency) section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f` |

## Request body

The note details

| Field | Type | Description |
|-------|------|-------------|
| `note_text` | string [max 5000 characters] | **Required.** Free-text content of the note. Max 5000 characters. Example: `Synced from CRM ticket` |

**Sample request**

```json
{
    "note_text": "Synced from CRM ticket"
}
```

## Responses

### 201 Note created

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"
}
```

### 409 Conflict - a request with this Idempotency-Key is currently being processed

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Example: `A request with this Idempotency-Key is already being processed.` |

**Sample response**

```json
{
    "message": "A request with this Idempotency-Key is already being processed."
}
```

### 422 Idempotency-Key was reused with a different request body

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Example: `Idempotency-Key was reused with a different request body.` |

**Sample response**

```json
{
    "message": "Idempotency-Key was reused with a different request body."
}
```

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