# Search

Base URL: `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none.

## GET /v1/search

Search media, playlists, screens and creatives

Search across media, playlists, screens, and creatives using the `q` query parameter. Supports bare terms, prefix matching with `*`, the operators AND, OR, and NOT, and column filters such as `name:dashboard`. Results are scoped to the current space.

Full-text search by name. Each list holds only kinds the caller may view (the others come back empty), best match first. A query under 2 characters returns empty lists.

**Notes.**
- The route is gated by `media.view` (the route-registry description says `screen.view`): a key without `media.view` is refused even if it could see screens.
- A failing index query is swallowed and returns an empty list for that kind, so an empty result is not proof of no match.

Auth: Bearer token. Permission: `media.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes | Search text (2+ characters). The last word matches as a prefix. |
| `limit` | query | integer | no | Hits per kind (default 10, max 20). |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.media` | array of object |  |
| `data.media[].id` | string |  |
| `data.media[].snippet` | string | Matched text with `<b>…</b>` around the hit. |
| `data.playlists` | array of object |  |
| `data.playlists[].id` | string |  |
| `data.playlists[].snippet` | string | Matched text with `<b>…</b>` around the hit. |
| `data.screens` | array of object |  |
| `data.screens[].id` | string |  |
| `data.screens[].snippet` | string | Matched text with `<b>…</b>` around the hit. |
| `data.creatives` | array of object |  |
| `data.creatives[].id` | string |  |
| `data.creatives[].snippet` | string | Matched text with `<b>…</b>` around the hit. |

Response 401: Missing, expired or revoked bearer token.

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

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

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

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

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