# Data sources

> 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/data-sources](#get-v1-data-sources)
- [POST /v1/data-sources](#post-v1-data-sources)
- [GET /v1/data-sources/{id}](#get-v1-data-sources-id)
- [PATCH /v1/data-sources/{id}](#patch-v1-data-sources-id)
- [DELETE /v1/data-sources/{id}](#delete-v1-data-sources-id)
- [POST /v1/data-sources/{id}/restore](#post-v1-data-sources-id-restore)
- [GET /v1/data-sources/{id}/revel/establishments](#get-v1-data-sources-id-revel-establishments)
- [PUT /v1/data-sources/{id}/revel/locations](#put-v1-data-sources-id-revel-locations)
- [POST /v1/data-sources/{id}/revel/test](#post-v1-data-sources-id-revel-test)
- [POST /v1/data-sources/{id}/sync](#post-v1-data-sources-id-sync)
- [POST /v1/data-sources/refresh-all](#post-v1-data-sources-refresh-all)
- [POST /v1/data-sources/revel/test](#post-v1-data-sources-revel-test)
- [GET /v1/data-sources/sheets-methods](#get-v1-data-sources-sheets-methods)
- [POST /v1/data-sources/test](#post-v1-data-sources-test)

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/data-sources

List data sources

List the data feeds, such as spreadsheets, APIs, and other connectors, that creatives and apps can connect to. Credentials are encrypted at rest and are never returned.

**Notes.**
- Not paginated: every data source you can see comes back in one response (no `?limit`/`?cursor`, unlike the app instance, creative and layout lists).

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of DataSource |  |
| `data[].id` | string | Data source id. |
| `data[].spaceId` | string |  |
| `data[].name` | string |  |
| `data[].type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. |
| `data[].config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. |
| `data[].cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. |
| `data[].rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. |
| `data[].connected` | boolean | The last sync succeeded. |
| `data[].lastSyncedAt` | string \| null |  |
| `data[].syncError` | string \| null | Why the last sync failed; null when it succeeded. |
| `data[].nodeId` | string \| null |  |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |

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/data-sources

Create a data source

Connect a data feed with a `name`, a connector `type`, a `config`, and an optional `nodeId`. Any credentials included in `config` are encrypted at rest. Test the configuration first with POST /v1/data-sources/test before creating it.

**Notes.**
- Gated by `integration.edit`, not `integration.create`.

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `type` | string | yes | Connector type from `GET /v1/connectors`. The value is not checked here: an unknown type fails at the first sync. |
| `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. |
| `nodeId` | string \| null | no | Home location; null or absent = workspace root. The key needs the permission there. |

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | DataSource | A connected data feed. Credentials are never returned. |
| `data.id` | string | Data source id. |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. |
| `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. |
| `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. |
| `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. |
| `data.connected` | boolean | The last sync succeeded. |
| `data.lastSyncedAt` | string \| null |  |
| `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. |
| `data.nodeId` | string \| null |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |

Response 401: Missing, expired or revoked bearer token.

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

Response 422: `name` or `type` is missing, or `invalid_node`: the location is not in this workspace.

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

## GET /v1/data-sources/{id}

Get a data source

Retrieve one data source, including its connector configuration, the time of its last sync, and its row schema. Secret values are redacted.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Data source id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | DataSource | A connected data feed. Credentials are never returned. |
| `data.id` | string | Data source id. |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. |
| `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. |
| `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. |
| `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. |
| `data.connected` | boolean | The last sync succeeded. |
| `data.lastSyncedAt` | string \| null |  |
| `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. |
| `data.nodeId` | string \| null |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |

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 data source in this workspace.

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

## PATCH /v1/data-sources/{id}

Update a data source

Edit a data source's name, connector configuration, or node.

Send `••••••••` back for a credential to keep the stored value. To point the source at a different address or connector type, enter the credential again.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Data source id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `type` | string | no | A change of type needs `config` with the credentials entered again. |
| `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. |
| `nodeId` | string \| null | no | Move it; the key needs `integration.edit` at the destination too. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | DataSource | A connected data feed. Credentials are never returned. |
| `data.id` | string | Data source id. |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.type` | string | Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`. |
| `data.config` | any | Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value. |
| `data.cachedData` | any \| null | The last successful fetch (JSON), or null before the first sync. Also null when `rowsWithheld` is true. |
| `data.rowsWithheld` | boolean | True when this caller may see the source but not its rows: HR, revenue, CRM and analytics sources need `integration.edit`. |
| `data.connected` | boolean | The last sync succeeded. |
| `data.lastSyncedAt` | string \| null |  |
| `data.syncError` | string \| null | Why the last sync failed; null when it succeeded. |
| `data.nodeId` | string \| null |  |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |

Response 401: Missing, expired or revoked bearer token.

Response 403: No `integration.edit` at the destination location.

Response 404: No such data source in this workspace.

Response 409: `conflict`: the type or config changed while this request ran. Nothing was saved; read the source again and resend.

Response 422: `credential_reentry_required`: the change moves a masked credential to a new address or connector type (`fields` names what moved); or `invalid_node`: the destination is not in this workspace.

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

## DELETE /v1/data-sources/{id}

Delete a data source. It can be restored later with POST /v1/data-sources/:id/restore. Creatives connected to it display their fallback values while it is deleted.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Data source id. |

```bash
curl -X DELETE "https://api.brixsignage.com/v1/data-sources/{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 data source in this workspace.

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

## POST /v1/data-sources/{id}/restore

Restore a deleted data source connector. Apps and creatives connected to it begin receiving fresh data again the next time their content refreshes.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Data source id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources/{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 data source in this workspace.

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

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

## GET /v1/data-sources/{id}/revel/establishments

List Revel establishments and locations

List the Revel establishments that the saved key can read, and the locations where this data source shows. Each location gives its chosen establishment and, when there is no choice, a suggested one.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl "https://api.brixsignage.com/v1/data-sources/{id}/revel/establishments" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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

## PUT /v1/data-sources/{id}/revel/locations

Set the Revel establishment for each location

Save which Revel establishment each location reads its menu from. Send `map` as `{ location id: establishment id }`. Each location must be one where this data source shows, and each establishment must be one that Revel lists for the key.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X PUT "https://api.brixsignage.com/v1/data-sources/{id}/revel/locations" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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

## POST /v1/data-sources/{id}/revel/test

Test a saved Revel connection

Check the Revel key that this data source holds. Send an optional `establishmentId` to check one establishment. Nothing is changed.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources/{id}/revel/test" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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

## POST /v1/data-sources/{id}/sync

Sync a data source now

Pull fresh data for one data source immediately instead of waiting for its regular schedule.

Runs the connector once and caches the result. A connector failure is NOT an HTTP error: the answer is 200 with `synced: false` and the reason.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Data source id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object \| object |  |

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 data source in this workspace.

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

## POST /v1/data-sources/refresh-all

Sync every data source

Pull fresh data for every data source in the workspace immediately. This action is rate-limited to 5 requests per minute.

Syncs, one after another, every data source the caller may edit. Rate limited to 5 calls a minute.

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

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources/refresh-all" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.total` | integer |  |
| `data.ok` | integer |  |
| `data.failed` | integer |  |

Response 401: Missing, expired or revoked bearer token.

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

Response 429: More than 5 calls in a minute.

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

## POST /v1/data-sources/revel/test

Test a Revel connection

Check a Revel address, API key and API secret before you save them. Send an optional `establishmentId` to check one establishment. Nothing is saved. The Revel connector must be turned on for the workspace.

Auth: Bearer token.

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources/revel/test" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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

## GET /v1/data-sources/sheets-methods

List Google Sheets sharing methods

List the ways a Google Sheet can be shared with the platform, and the address to share it with. The response may include `publicLink`, `serviceAccount`, and `oauth`, depending on what the platform supports; a method is listed only if it is actually available. `serviceAccount` is not a secret; it is the address you enter into Google's Share dialog.

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

```bash
curl "https://api.brixsignage.com/v1/data-sources/sheets-methods" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.publicLink` | true | A sheet shared as "anyone with the link" always works. |
| `data.serviceAccount` | string \| null | The address to share a private sheet with; null when this method is not available. |
| `data.oauth` | boolean | A private sheet can be picked by signing in with Google. |

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/data-sources/test

Test a data source config

Validate a connector configuration without saving it. Returns `{ ok: true, preview }` on success or `{ ok: false, error }` on failure, so a misconfigured feed can be caught before it is created.

Runs the connector once with a config that is not saved. A connector failure is NOT an HTTP error: the answer is 200 with `ok: false` and the reason. Rate limited to 20 calls a minute.

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes |  |
| `config` | object | no | Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`. |

```bash
curl -X POST "https://api.brixsignage.com/v1/data-sources/test" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object \| object |  |

Response 401: Missing, expired or revoked bearer token.

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

Response 429: More than 20 calls in a minute.

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