Web recorder API
Web recorder endpoints in the Brix REST API: 6 operations (GET, POST). Each lists its path, auth, required permission and a curl example.
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
GET /v1/web-recorder/{sid}POST /v1/web-recorder/{sid}/abortPOST /v1/web-recorder/{sid}/actionPOST /v1/web-recorder/{sid}/finalizePOST /v1/web-recorder/links/{mediaId}/verifyPOST /v1/web-recorder/start
GET/v1/web-recorder/{sid}
Return the steps recorded so far in an in-progress sign-in recording session.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
sid | path | string | yes | Recording session id, from `start`. |
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.
| 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 404 No active session with this id in this workspace (it expired, was finished, or never started).
| 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 503 Recording is not available in this environment.
| 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. |
POST/v1/web-recorder/{sid}/abort
Discard an in-progress sign-in recording session without changing the associated media asset.
**Notes.**
- Always answers { ok: true }, for an unknown session too.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
sid | path | string | yes | Recording session id, from `start`. |
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.
| 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. |
POST/v1/web-recorder/{sid}/action
Append one recorded interaction, such as a click, typed text, or a wait, to an open sign-in recording session.
| Parameter | 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 |
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.
| 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 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 404 No active session with this id in this workspace (it expired, was finished, or never started).
| 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 503 Recording is not available in this environment.
| 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. |
POST/v1/web-recorder/{sid}/finalize
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.
| Parameter | 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. |
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.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.
| 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 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 You do not hold `media.edit` where the asset lives.
| 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 404 The session expired or never started, or no such asset.
| 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 503 Recording is not available in this environment.
| 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. |
POST/v1/web-recorder/links/{mediaId}/verify
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
mediaId | path | string | yes | Web page asset id. |
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.
| 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 You do not hold `media.edit` where the asset lives.
| 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 503 The headless browser is not available.
| 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. |
POST/v1/web-recorder/start
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.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | The sign-in page (http or https, a public host). |
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.
| 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 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 503 Recording is not available in this environment.
| 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. |