# Notes

Notes attached to tabs and orders

## GET /api/v1/notes

List notes for an entity

List all notes attached to a specific entity (tab or user). Notes are returned in sort order (lowest sortOrder first).

**Permissions:** 🔵 `notes.read`

Query parameters:
- `entityType` ("tab" | "user" | "booking", required) — Type of entity to fetch notes for
- `entityId` (string, required) — ID of the entity (tab UUID or user ID)

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    notes: Array<{
        uuid: string // uuid
        entityType: "tab" | "user" | "booking"
        entityId: string
        note: string
        locationId: number
        sortOrder: number
        createdByRetailerUserId?: number | null
        createdByName?: string | null
        updatedByRetailerUserId?: number | null
        updatedByName?: string | null
        createdAt: string // date-time
        updatedAt: string // date-time
      }>
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/notes

Create a note

Create a new note attached to an entity (tab or user). The note will be associated with the current location and the authenticated user (if using JWT auth).

**Permissions:** 🟢 `notes.create`

Request body:

```ts
{
  entityType: "tab" | "user" | "booking"
  entityId: string
  note: string
}
```

Response 201 — Default Response

```ts
{
  status: "success"
  data: {
    uuid: string // uuid
    entityType: "tab" | "user" | "booking"
    entityId: string
    note: string
    locationId: number
    sortOrder: number
    createdByRetailerUserId?: number | null
    createdByName?: string | null
    updatedByRetailerUserId?: number | null
    updatedByName?: string | null
    createdAt: string // date-time
    updatedAt: string // date-time
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## GET /api/v1/notes/{uuid}

Get a note

Get a single note by UUID

**Permissions:** 🔵 `notes.read`

Path parameters:
- `uuid` (string, required) — Note UUID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    uuid: string // uuid
    entityType: "tab" | "user" | "booking"
    entityId: string
    note: string
    locationId: number
    sortOrder: number
    createdByRetailerUserId?: number | null
    createdByName?: string | null
    updatedByRetailerUserId?: number | null
    updatedByName?: string | null
    createdAt: string // date-time
    updatedAt: string // date-time
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## DELETE /api/v1/notes/{uuid}

Delete a note

Delete a note by UUID

**Permissions:** 🔴 `notes.delete`

Path parameters:
- `uuid` (string, required) — Note UUID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    deleted: true
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## PATCH /api/v1/notes/{uuid}

Update a note

Update an existing note. The updated_by fields will be set to the authenticated user.

**Permissions:** 🟠 `notes.update`

Path parameters:
- `uuid` (string, required) — Note UUID

Request body:

```ts
{
  note: string
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    uuid: string // uuid
    entityType: "tab" | "user" | "booking"
    entityId: string
    note: string
    locationId: number
    sortOrder: number
    createdByRetailerUserId?: number | null
    createdByName?: string | null
    updatedByRetailerUserId?: number | null
    updatedByName?: string | null
    createdAt: string // date-time
    updatedAt: string // date-time
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/notes/reorder

Reorder notes

Reorder notes for an entity. Pass an array of note UUIDs in the desired order. Each note will have its sortOrder updated to match its position in the array.

**Permissions:** 🟠 `notes.update`

Query parameters:
- `entityType` ("tab" | "user" | "booking", required) — Type of entity to fetch notes for
- `entityId` (string, required) — ID of the entity (tab UUID or user ID)

Request body:

```ts
{
  noteUuids: string[]
}
```

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    notes: Array<{
        uuid: string // uuid
        entityType: "tab" | "user" | "booking"
        entityId: string
        note: string
        locationId: number
        sortOrder: number
        createdByRetailerUserId?: number | null
        createdByName?: string | null
        updatedByRetailerUserId?: number | null
        updatedByName?: string | null
        createdAt: string // date-time
        updatedAt: string // date-time
      }>
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```