# Web recorder

> 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/web-recorder/{sid}](#get-v1-web-recorder-sid)
- [POST /v1/web-recorder/{sid}/abort](#post-v1-web-recorder-sid-abort)
- [POST /v1/web-recorder/{sid}/action](#post-v1-web-recorder-sid-action)
- [POST /v1/web-recorder/{sid}/finalize](#post-v1-web-recorder-sid-finalize)
- [POST /v1/web-recorder/links/{mediaId}/verify](#post-v1-web-recorder-links-mediaid-verify)
- [POST /v1/web-recorder/start](#post-v1-web-recorder-start)

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/web-recorder/{sid}

Get a recording session

Return the steps recorded so far in an in-progress sign-in recording session.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | path | string | yes | Recording session id, from `start`. |

```bash
curl "https://api.brixsignage.com/v1/web-recorder/{sid}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.url` | string | The page the recording is on now. |
| `data.steps` | array of RecordedStep |  |
| `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. |
| `data.steps[].url` | string |  |
| `data.steps[].selector` | string |  |
| `data.steps[].label` | string |  |
| `data.steps[].value` | string | Typed text that is not secret. |
| `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. |
| `data.steps[].pixels` | number |  |
| `data.steps[].ms` | number |  |
| `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). |
| `data.spaceId` | string |  |

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 active session with this id in this workspace (it expired, was finished, or never started).

Response 503: Recording is not available in this environment.

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

## POST /v1/web-recorder/{sid}/abort

Cancel a recording

Discard an in-progress sign-in recording session without changing the associated media asset.

**Notes.**
- Always answers `{ ok: true }`, for an unknown session too.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | path | string | yes | Recording session id, from `start`. |

```bash
curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/abort" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |

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/web-recorder/{sid}/action

Record a sign-in step

Append one recorded interaction, such as a click, typed text, or a wait, to an open sign-in recording session.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | path | string | yes | Recording session id, from `start`. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | "click" \| "type" \| "scroll" \| "navigate" \| "accept-cookies" \| "wait" \| "pick" | yes |  |
| `selector` | string | no |  |
| `label` | string | no |  |
| `text` | string | no | For `type`: the typed text (not stored when `isSecret`). |
| `isSecret` | boolean | no | For `type`: store a reference instead of the text. |
| `url` | string | no |  |
| `dy` | number | no |  |
| `ms` | number | no |  |
| `mode` | string | no |  |
| `x` | number | no |  |
| `y` | number | no |  |

```bash
curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/action" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.url` | string | The page the recording is on now. |
| `data.steps` | array of RecordedStep |  |
| `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. |
| `data.steps[].url` | string |  |
| `data.steps[].selector` | string |  |
| `data.steps[].label` | string |  |
| `data.steps[].value` | string | Typed text that is not secret. |
| `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. |
| `data.steps[].pixels` | number |  |
| `data.steps[].ms` | number |  |
| `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). |
| `data.spaceId` | string |  |

Response 400: The body is not JSON.

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 active session with this id in this workspace (it expired, was finished, or never started).

Response 503: Recording is not available in this environment.

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

## POST /v1/web-recorder/{sid}/finalize

Save a recorded sign-in

Save a completed recording to a web asset, using mediaId and optional secrets. The recorded steps are stored on the asset's web configuration, secrets are encrypted and referenced by name, and the session ends.

**Notes.**
- The asset's sign-in is replayed later to refresh its cookies; call `links/:mediaId/verify` to test it now.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sid` | path | string | yes | Recording session id, from `start`. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mediaId` | string | yes | The web page asset to save the steps to. |
| `secrets` | object | no | `valueRef` → secret value. Encrypted; never returned. Null or empty removes one. |
| `expect` | object | no | The asset's `url` and `webConfig` as you last read them. The save is refused (409) if the address or sign-in steps changed since, so secrets are never stored for a link you did not see. |
| `expect.url` | string | yes |  |
| `expect.webConfig` | any | yes |  |
| `removeSteps` | array of integer | no | Indices into the session's steps to leave out of the saved recording. |

```bash
curl -X POST "https://api.brixsignage.com/v1/web-recorder/{sid}/finalize" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |
| `data.stepCount` | integer |  |
| `data.steps` | array of RecordedStep | The steps saved on the asset (the session's, minus `removeSteps`). |
| `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. |
| `data.steps[].url` | string |  |
| `data.steps[].selector` | string |  |
| `data.steps[].label` | string |  |
| `data.steps[].value` | string | Typed text that is not secret. |
| `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. |
| `data.steps[].pixels` | number |  |
| `data.steps[].ms` | number |  |
| `data.secretRefs` | array of object | Every secret step, so you can send values you have not sent yet. |
| `data.secretRefs[].ref` | string |  |
| `data.secretRefs[].label` | string |  |

Response 400: `mediaId` is missing.

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `media.edit` where the asset lives.

Response 404: The session expired or never started, or no such asset.

Response 409: The asset's address or sign-in steps changed (or are not what `expect` says). Nothing was saved.

Response 503: Recording is not available in this environment.

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

## POST /v1/web-recorder/links/{mediaId}/verify

Test a recorded sign-in

Run the finalized sign-in recording for a web asset and report whether the resulting session looks successfully logged in. This lets a caller confirm the recording works right after capturing it, rather than waiting until the content plays on a screen.

**Notes.**
- Runs the sign-in in a headless browser now (this can take 30 seconds or more). Answers 200 with `ok: false` when it fails.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `mediaId` | path | string | yes | Web page asset id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/web-recorder/links/{mediaId}/verify" \
  -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: You do not hold `media.edit` where the asset lives.

Response 503: The headless browser is not available.

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

## POST /v1/web-recorder/start

Start recording a sign-in

Begin a sign-in recording session for a web asset, given a url. Returns a session id, the url, and the steps recorded so far, which starts empty. Steps are then submitted using the Brix Recorder browser extension.

**Notes.**
- The recorder browser extension then sends each step with `action`. Invalid input answers 400, not 422.

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The sign-in page (http or https, a public host). |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.url` | string | The page the recording is on now. |
| `data.steps` | array of RecordedStep |  |
| `data.steps[].kind` | string | `navigate`, `click`, `enter-text`, `scroll`, `accept-cookies`, `wait`, or a picker step. |
| `data.steps[].url` | string |  |
| `data.steps[].selector` | string |  |
| `data.steps[].label` | string |  |
| `data.steps[].value` | string | Typed text that is not secret. |
| `data.steps[].valueRef` | string | For secret text: a reference; the value is never recorded. Send it in `finalize`'s `secrets`. |
| `data.steps[].pixels` | number |  |
| `data.steps[].ms` | number |  |
| `data.startedAt` | integer | Milliseconds since the Unix epoch (not an ISO timestamp). |
| `data.spaceId` | string |  |
| `data.sid` | string |  |
| `data.ok` | true |  |

Response 400: `url` is not http(s), or not a public address.

Response 401: Missing, expired or revoked bearer token.

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

Response 503: Recording is not available in this environment.

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