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.

View as Markdown · For AI agents: the full docs index is at /llms.txt

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, Errors and rate limits and Pagination.

GET /v1/web-recorder/{sid}
POST /v1/web-recorder/{sid}/abort
POST /v1/web-recorder/{sid}/action
POST /v1/web-recorder/{sid}/finalize
POST /v1/web-recorder/links/{mediaId}/verify
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}

Auth: Bearer token. Permission: media.edit.

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.

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

Auth: Bearer token. Permission: media.edit.

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.

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

Auth: Bearer token. Permission: media.edit.

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.

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

Auth: Bearer token. Permission: media.edit.

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

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

Auth: Bearer token. Permission: media.edit.

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.

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

Auth: Bearer token. Permission: media.edit.

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.

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.

GET /v1/web-recorder/{sid}

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

POST /v1/web-recorder/{sid}/action

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

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

POST /v1/web-recorder/start

Connect With Us

Message Received!