# Celebration entries

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Base URL `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See [Authentication and scopes](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/celebration-entries](#get-v1-celebration-entries)
- [POST /v1/celebration-entries](#post-v1-celebration-entries)
- [GET /v1/celebration-entries/{id}](#get-v1-celebration-entries-id)
- [PATCH /v1/celebration-entries/{id}](#patch-v1-celebration-entries-id)
- [DELETE /v1/celebration-entries/{id}](#delete-v1-celebration-entries-id)
- [POST /v1/celebration-entries/{id}/restore](#post-v1-celebration-entries-id-restore)

Every 4xx and 5xx response below returns this body:

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## GET /v1/celebration-entries

List celebration entries

Return the roster of birthdays, anniversaries, and other occasions that the Celebrations app displays.

**Notes.**
- Only entries at locations the caller can see.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Page size. Omit to get every row; pass it to page by `cursor`. |
| `cursor` | query | string | no | The `nextCursor` of the previous page. |
| `count` | query | "1" | no | With `limit`: also return `total`, the number of matching rows. |
| `usableAt` | query | string | no | Location id: only rows usable at that location (homed there, at the workspace root, or shared to it). |

```bash
curl "https://api.brixsignage.com/v1/celebration-entries" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of CelebrationEntry |  |
| `data[].id` | string |  |
| `data[].spaceId` | string |  |
| `data[].nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. |
| `data[].sourceId` | string \| null | The data source it came from, if any. |
| `data[].name` | string |  |
| `data[].photoUrl` | string \| null |  |
| `data[].occasionType` | "birthday" \| "anniversary" \| "custom" |  |
| `data[].occasionMonth` | integer \| null | 1–12. |
| `data[].occasionDay` | integer \| null | 1–31. |
| `data[].occasionYear` | integer \| null | The start year for an anniversary. |
| `data[].department` | string \| null |  |
| `data[].title` | string \| null |  |
| `data[].location` | string \| null |  |
| `data[].customMessage` | string \| null |  |
| `data[].externalId` | string \| null | The id in the source system, for de-duplication. |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].deletedAt` | string \| null |  |
| `nextCursor` | string \| null | Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page. |
| `total` | integer | Total matching rows, when the route computes it. |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/celebration-entries

Create a celebration entry

Add an entry to the celebration roster. Requires name; also accepts occasionType, occasionMonth, occasionDay, occasionYear, photoUrl, department, title, location, customMessage, sourceId, and externalId, all optional.

**Notes.**
- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.

Auth: Bearer token. Permission: `integration.create`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `sourceId` | string \| null | no |  |
| `photoUrl` | string \| null | no |  |
| `occasionType` | "birthday" \| "anniversary" \| "custom" | no | Default `birthday`. |
| `occasionMonth` | integer \| null | no |  |
| `occasionDay` | integer \| null | no |  |
| `occasionYear` | integer \| null | no |  |
| `department` | string \| null | no |  |
| `title` | string \| null | no |  |
| `location` | string \| null | no |  |
| `customMessage` | string \| null | no |  |
| `externalId` | string \| null | no |  |
| `nodeId` | string \| null | no |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/celebration-entries" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sam Rivera","occasionType":"birthday","occasionMonth":10,"occasionDay":4,"department":"Kitchen"}'
```

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. |
| `data.sourceId` | string \| null | The data source it came from, if any. |
| `data.name` | string |  |
| `data.photoUrl` | string \| null |  |
| `data.occasionType` | "birthday" \| "anniversary" \| "custom" |  |
| `data.occasionMonth` | integer \| null | 1–12. |
| `data.occasionDay` | integer \| null | 1–31. |
| `data.occasionYear` | integer \| null | The start year for an anniversary. |
| `data.department` | string \| null |  |
| `data.title` | string \| null |  |
| `data.location` | string \| null |  |
| `data.customMessage` | string \| null |  |
| `data.externalId` | string \| null | The id in the source system, for de-duplication. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `integration.create` at the location.

Response 422: `name` is missing, or a location or data source outside this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/celebration-entries/{id}

Get a celebration entry

Return one entry from the celebration roster.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Celebration entry id. |

```bash
curl "https://api.brixsignage.com/v1/celebration-entries/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | CelebrationEntry | A person's birthday, work anniversary or other occasion for the Celebrations app. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. |
| `data.sourceId` | string \| null | The data source it came from, if any. |
| `data.name` | string |  |
| `data.photoUrl` | string \| null |  |
| `data.occasionType` | "birthday" \| "anniversary" \| "custom" |  |
| `data.occasionMonth` | integer \| null | 1–12. |
| `data.occasionDay` | integer \| null | 1–31. |
| `data.occasionYear` | integer \| null | The start year for an anniversary. |
| `data.department` | string \| null |  |
| `data.title` | string \| null |  |
| `data.location` | string \| null |  |
| `data.customMessage` | string \| null |  |
| `data.externalId` | string \| null | The id in the source system, for de-duplication. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such entry in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PATCH /v1/celebration-entries/{id}

Update a celebration entry

Edit one entry in the celebration roster. Accepts any of the fields used when creating an entry.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Celebration entry id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `sourceId` | string \| null | no |  |
| `photoUrl` | string \| null | no |  |
| `occasionType` | "birthday" \| "anniversary" \| "custom" | no | Default `birthday`. |
| `occasionMonth` | integer \| null | no |  |
| `occasionDay` | integer \| null | no |  |
| `occasionYear` | integer \| null | no |  |
| `department` | string \| null | no |  |
| `title` | string \| null | no |  |
| `location` | string \| null | no |  |
| `customMessage` | string \| null | no |  |
| `externalId` | string \| null | no |  |
| `nodeId` | string \| null | no |  |

```bash
curl -X PATCH "https://api.brixsignage.com/v1/celebration-entries/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | CelebrationEntry | A person's birthday, work anniversary or other occasion for the Celebrations app. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. Follows the data source's location when not set. |
| `data.sourceId` | string \| null | The data source it came from, if any. |
| `data.name` | string |  |
| `data.photoUrl` | string \| null |  |
| `data.occasionType` | "birthday" \| "anniversary" \| "custom" |  |
| `data.occasionMonth` | integer \| null | 1–12. |
| `data.occasionDay` | integer \| null | 1–31. |
| `data.occasionYear` | integer \| null | The start year for an anniversary. |
| `data.department` | string \| null |  |
| `data.title` | string \| null |  |
| `data.location` | string \| null |  |
| `data.customMessage` | string \| null |  |
| `data.externalId` | string \| null | The id in the source system, for de-duplication. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `integration.edit` at the destination location.

Response 404: No such entry in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## DELETE /v1/celebration-entries/{id}

Delete a celebration entry

Remove an entry from the celebration roster. The entry moves to the recycle bin and can be brought back with the restore operation.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Celebration entry id. |

```bash
curl -X DELETE "https://api.brixsignage.com/v1/celebration-entries/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.deleted` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such entry in this workspace.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/celebration-entries/{id}/restore

Restore a celebration entry

Bring back a deleted celebration entry so it appears again in the celebration app's roster.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Celebration entry id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/celebration-entries/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.restored` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such entry in this workspace, or it was purged.

Response 409: `not_deleted`: the entry is not in the recycle bin.

Response 5XX: Server error. The body carries a `requestId` to quote to support.
