Media API (part 2 of 3)

Media endpoints in the Brix REST API, part 2 of 3: 22 operations from /v1/media/{id}, each with auth, permission and curl.

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.

Media is split into 3 pages: part 1 (/v1/media to /v1/media/{id}), part 2 (/v1/media/{id} to /v1/media/{id}/web-secrets), part 3 (/v1/media/backfill-avif to /v1/media/upload/package).

DELETE /v1/media/{id}
GET /v1/media/{id}/captions
POST /v1/media/{id}/captions
POST /v1/media/{id}/captions/transcribe
POST /v1/media/{id}/captions/upload
POST /v1/media/{id}/captions/visibility
GET /v1/media/{id}/delta
GET /v1/media/{id}/file
POST /v1/media/{id}/focal-region
GET /v1/media/{id}/lan-preview
POST /v1/media/{id}/lan-preview
GET /v1/media/{id}/lan-preview/file
GET /v1/media/{id}/playback-quality
GET /v1/media/{id}/poster
POST /v1/media/{id}/poster
POST /v1/media/{id}/render
GET /v1/media/{id}/render-frame
POST /v1/media/{id}/restore
POST /v1/media/{id}/rotate
POST /v1/media/{id}/suggest
GET /v1/media/{id}/usage
PUT /v1/media/{id}/web-secrets

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.

DELETE /v1/media/{id}

Auth: Bearer token. Permission: media.delete.

Move a media asset to the recycle bin. Playlists and screens that reference it show a gap where the asset was until it is restored or replaced. Moves the asset to the recycle bin (restorable for 30 days) and removes it from every playlist. Screens casting it return to their schedule.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.
`force`	query	"true"	no	Delete even when it is shared into other places.

curl -X DELETE "https://api.brixsignage.com/v1/media/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.id`	string
`data.deleted`	true
`data.sharesRemoved`	integer	Shares removed with it.

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

Response 409: content_shared: the item is shared into other places; shareCount, crossSpaceShares, contentShares say where. Repeat with ?force=true to delete it and those shares.

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

GET /v1/media/{id}/captions

Auth: Bearer token. Permission: media.view.

Return a video's caption track as WebVTT. Add ?lang= to request a machine-translated version, for example ?lang=es for Spanish. This URL is stable, so it can be referenced directly by a player.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.
`lang`	query	string	no	Two- or three-letter language code: a machine translation of the track (default: the original).

curl "https://api.brixsignage.com/v1/media/{id}/captions" \
  -H "Authorization: Bearer $BRIX_API_KEY"

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 media with this id, or it has no captions.

Response 429: More than 60 reads a minute.

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

POST /v1/media/{id}/captions

Auth: Bearer token. Permission: media.edit.

Automatically generate a caption track for a video from its audio and attach it to the asset. To upload a caption file instead, use the caption upload operation. To show or hide an existing caption track, use the caption visibility operation.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.ok`	true
`data.key`	string	Storage path of the caption track.
`data.state`	"ready"

Response 400: wrong_kind: not a video.

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 media with this id, or no bytes.

Response 413: Over 40 MB: send the audio to /captions/transcribe instead.

Response 502: transcription_failed.

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

POST /v1/media/{id}/captions/transcribe

Auth: Bearer token. Permission: media.edit.

Convert a short audio clip, extracted from a video as 16 kHz mono WAV, into a caption track. Use this instead of the standard caption-generation operation when the full video file is too large to process directly.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/transcribe" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.ok`	true
`data.key`	string	Storage path of the caption track.
`data.state`	"ready"

Response 400: wrong_kind: not a video.

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 media with this id.

Response 413: Over 20 MB.

Response 422: Empty body.

Response 502: transcription_failed.

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

POST /v1/media/{id}/captions/upload

Auth: Bearer token. Permission: media.edit.

Attach a caption file to a video. SRT files are converted to WebVTT; WebVTT files are stored as-is. This is the alternative to automatic caption generation.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/upload" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.ok`	true
`data.key`	string	Storage path of the caption track.
`data.state`	"ready"

Response 400: wrong_kind: not a video.

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 media with this id.

Response 413: Over 5 MB.

Response 415: Not a .vtt or .srt track.

Response 422: Empty body.

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

POST /v1/media/{id}/captions/visibility

Auth: Bearer token. Permission: media.edit.

Turn a video's caption track on or off for playback. Hiding the track keeps it in storage so it can be shown again later. If no caption track exists yet, the response indicates that one must be generated first.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

Request body: application/json

Field	Type	Required	Description
`show`	boolean	no	True shows captions; anything else hides them.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/captions/visibility" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200: Success.

Field	Type	Description
`data`	object
`data.state`	"hidden" \| "ready" \| "needs_audio"	`needs_audio`: shown, but the video has no caption track yet.

Response 400: wrong_kind: not a video.

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 media with this id.

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

GET /v1/media/{id}/delta

Auth: Bearer token. Permission: media.view.

Used by playback devices to check whether their cached copy of a file is current. The caller sends the checksum of its cached copy and receives either the data needed to update it, or a flag indicating no partial update is available along with a URL to download the full file. Notes. - Reserved: delta downloads are not offered yet, so this always answers deltaAvailable: false.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl "https://api.brixsignage.com/v1/media/{id}/delta" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.deltaAvailable`	false
`data.downloadUrl`	null

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.

GET /v1/media/{id}/file

Auth: Bearer token. Permission: media.view.

Stream the media asset's file bytes. Supports HTTP Range requests for partial downloads. Notes. - HTML, SVG and script files are served as application/octet-stream attachments, never inline.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.
`w`	query	string	no	Images: resize to this width (a thumbnail).
`h`	query	string	no	Images: resize to this height.
`fit`	query	"cover" \| "contain" \| "scale-down" \| "crop" \| "pad"	no	How a resized copy fits `w` × `h` (default `cover`).

curl "https://api.brixsignage.com/v1/media/{id}/file" \
  -H "Authorization: Bearer $BRIX_API_KEY"

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 media with this id, or the file is not in storage.

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

POST /v1/media/{id}/focal-region

Auth: Bearer token. Permission: media.edit.

Detect the main subject of an image and cache its position as a normalized x, y, width, and height. This lets the image be cropped around its subject when shown in a differently shaped area, instead of being cropped from the center.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/focal-region" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.region`	object \| null	Fractions (0–1) of the image. Null when nothing stood out; the stored region is then unchanged.

Response 400: wrong_kind: not an image.

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 media with this id, or no bytes.

Response 413: Over 32 MB.

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

GET /v1/media/{id}/lan-preview

Auth: Bearer token. Permission: media.view.

Read the newest picture a screen took of this on-network web page, and the state of the newest request for one. A web page on a local network cannot be reached from the cloud, so only a screen on that network can take the picture.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Identifier for id.

curl "https://api.brixsignage.com/v1/media/{id}/lan-preview" \
  -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/media/{id}/lan-preview

Auth: Bearer token. Permission: screen.command-sent.

Ask an online screen to take a picture of this on-network web page. Screens the page is assigned to are tried first, then its location, then the workspace. A second request within 30 seconds joins the one already running. Answers 422 for a page that is not on-network.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Identifier for id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/lan-preview" \
  -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/media/{id}/lan-preview/file

Auth: Bearer token.

Download the newest picture a screen took of this on-network web page.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Identifier for id.

curl "https://api.brixsignage.com/v1/media/{id}/lan-preview/file" \
  -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/media/{id}/playback-quality

Auth: Bearer token. Permission: media.view.

Return dropped-frame data reported by screens that have played this video, used to flag videos that are not playing smoothly. A null health value means the asset has not been measured yet, not that it is playing well.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl "https://api.brixsignage.com/v1/media/{id}/playback-quality" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.failures`	object \| null	Null when the item failed on no screen in the window.
`data.health`	object \| null	Null until a screen reports on this video.
`data.stutterDropPct`	number	Dropped-frame percentage above which a screen counts as struggling.
`data.minSamplesToWarn`	integer
`data.screens`	array of object
`data.screens[].screenId`	string
`data.screens[].worstDropPct`	number
`data.screens[].meanDropPct`	number
`data.screens[].samples`	integer
`data.screens[].videoWidth`	integer \| null
`data.screens[].videoHeight`	integer \| null
`data.screens[].lastSeenAt`	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.

GET /v1/media/{id}/poster

Auth: Bearer token. Permission: media.view.

Return the poster image attached to a media asset, used as its thumbnail for videos and PDFs.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.
`w`	query	string	no	Resize to this width.
`h`	query	string	no	Resize to this height.
`fit`	query	"cover" \| "contain" \| "scale-down" \| "crop" \| "pad"	no

curl "https://api.brixsignage.com/v1/media/{id}/poster" \
  -H "Authorization: Bearer $BRIX_API_KEY"

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 media with this id, or it has no poster.

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

POST /v1/media/{id}/poster

Auth: Bearer token. Permission: media.edit.

Attach a poster image to a media asset, used as its thumbnail. The file must be an image and no larger than 4 MB. Notes. - With ?generate=1 the body is { thumbnailUrl, generated } and no request body is read.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.
`generate`	query	"1"	no	`1`: generate the poster from the media itself (send no body).

curl -X POST "https://api.brixsignage.com/v1/media/{id}/poster" \
  -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 media with this id.

Response 413: Over 4 MB.

Response 415: Not a recognised image.

Response 422: Empty body.

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

POST /v1/media/{id}/render

Auth: Bearer token. Permission: media.edit.

Capture and store a screenshot of a web or link asset. If screenshot rendering is not available for this workspace, the response reports that it is not configured rather than failing. Notes. - Usually queued (queued: true); the frame is then at GET /v1/media/{id}/render-frame. - A second request while a render of the same link with the same settings is still queued or running returns queued: true and adds nothing. After an edit, the request queues a render of the new settings.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/render" \
  -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 media with this id.

Response 429: More than 60 renders a minute, or the workspace already has 4 web renders queued (renders_busy, retry after the Retry-After).

Response 502: The render failed.

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

GET /v1/media/{id}/render-frame

Auth: Bearer token. Permission: media.view.

Return the most recent screenshot generated for a web or link asset by the render operation.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl "https://api.brixsignage.com/v1/media/{id}/render-frame" \
  -H "Authorization: Bearer $BRIX_API_KEY"

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 media with this id, or the link has not been rendered yet (a render is then queued).

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

POST /v1/media/{id}/restore

Auth: Bearer token. Permission: media.delete.

Bring back a deleted media asset. Any playlist or screen still referencing it resumes rendering it.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{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 media with this id.

Response 409: not_deleted: it is not in the recycle bin.

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

POST /v1/media/{id}/rotate

Auth: Bearer token. Permission: media.edit.

Rotate a photo or video 90, 180, or 270 degrees clockwise. This rewrites the stored file rather than only changing how it is displayed, since playback devices cannot rotate video at display time. Images are rotated immediately; video rotation is queued, and the asset keeps playing its current version until the rotated file is ready. Notes. - Photos rotate now (rotated); videos are re-encoded in the background (queued).

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

Request body: application/json

Field	Type	Required	Description
`degrees`	90 \| 180 \| 270	yes	Clockwise.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/rotate" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200: Success.

Field	Type	Description
`data`	object \| object

Response 400: degrees is not 90, 180 or 270, or the item is not a photo or video.

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 media with this id, or its bytes are gone.

Response 409: A rotation is already running.

Response 502: The image service failed.

Response 503: Rotation is not available.

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

POST /v1/media/{id}/suggest

Auth: Bearer token. Permission: media.edit.

Analyze an image asset and return suggested altText and tags. This only returns suggestions; it does not save them, so use the update-media-asset operation to accept them. Only images are supported. If this feature is temporarily unavailable, the response returns empty values rather than failing. Notes. - Suggestions only: nothing is saved.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl -X POST "https://api.brixsignage.com/v1/media/{id}/suggest" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	object
`data.altText`	string \| null
`data.tags`	array of string

Response 400: wrong_kind: not an image.

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 media with this id, or no bytes.

Response 413: Over 32 MB.

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

GET /v1/media/{id}/usage

Auth: Bearer token. Permission: media.view.

Return where a media asset is used, across playlists, creatives, and layouts, along with when it was last played.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

curl "https://api.brixsignage.com/v1/media/{id}/usage" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Field	Type	Description
`data`	MediaUsage
`data.containers`	array of object
`data.containers[].id`	string
`data.containers[].name`	string
`data.containers[].kind`	"playlist" \| "schedule" \| "layout" \| "creative" \| "signage"	`signage` = a signage template (board).
`data.containers[].itemCount`	integer	Playlists only: total items in the playlist.
`data.screens`	array of object	Active screens showing it now, directly or through one of the containers.
`data.screens[].id`	string
`data.screens[].name`	string
`data.screens[].location`	string \| null
`data.screens[].status`	string	`online`, `offline` or `pairing`.
`data.lastPlayedAt`	string \| null	Last completed play reported by a screen; null if never played.

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

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

PUT /v1/media/{id}/web-secrets

Auth: Bearer token. Permission: media.edit.

Store credentials, such as authentication tokens or login passwords, for a web asset. Values are encrypted at rest and write-only: send an object mapping reference names to values, where a null value deletes that reference. Only the reference names, never the values, can be read back later. This merges with any existing secrets rather than replacing them.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media asset id.

Request body: application/json

Field	Type	Required	Description
`secrets`	object	yes	Secret name → value (at most 50, values ≤ 8192 characters). `null` or `""` removes one; names not sent are kept.
`expect`	object	no	The link's `url` and `webConfig` as you last read them. Send it: the secrets are stored only if the link still sends them to that address and those sign-in steps, else 409.
`expect.url`	string	yes
`expect.webConfig`	any	yes

curl -X PUT "https://api.brixsignage.com/v1/media/{id}/web-secrets" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200: Success.

Field	Type	Description
`data`	object
`data.ok`	true
`data.refs`	array of string	The secret NAMES now stored. Values are never returned.

Response 400: Too many secrets, a name or value too long, or a malformed expect.

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 media with this id.

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

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

DELETE /v1/media/{id}

GET /v1/media/{id}/captions

POST /v1/media/{id}/captions

POST /v1/media/{id}/captions/transcribe

POST /v1/media/{id}/captions/upload

POST /v1/media/{id}/captions/visibility

GET /v1/media/{id}/delta

GET /v1/media/{id}/file

POST /v1/media/{id}/focal-region

GET /v1/media/{id}/lan-preview

POST /v1/media/{id}/lan-preview

GET /v1/media/{id}/lan-preview/file

GET /v1/media/{id}/playback-quality

GET /v1/media/{id}/poster

POST /v1/media/{id}/poster

POST /v1/media/{id}/render

GET /v1/media/{id}/render-frame

POST /v1/media/{id}/restore

POST /v1/media/{id}/rotate

POST /v1/media/{id}/suggest

GET /v1/media/{id}/usage

PUT /v1/media/{id}/web-secrets

Connect With Us

Message Received!