Media API (part 1 of 3)

GET /v1/media

Auth: Bearer token. Permission: media.view.

Return the media library: images, videos, PDFs, presentations, fonts, web links, and app-backed assets. Use limit and cursor to page through results, count=1 to include a total count, search to search by name or tag, and the comma-separated kind, state, and folderId parameters to filter. Paging is optional but recommended, since a library can hold thousands of items. Without limit, every visible asset comes back unordered and without nextCursor. With limit, rows are newest first.

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

Response 200: Success.

{
  "data": [
    {
      "id": "med_0c1d2e3f4a5b6c7d",
      "spaceId": "space_1a2b3c4d5e6f7a8b",
      "name": "lunch-special.jpg",
      "kind": "image",
      "url": "/v1/media/med_0c1d2e3f4a5b6c7d/file",
      "bytes": 482113,
      "checksum": null,
      "active": true,
      "folderId": null,
      "tags": [
        "menu",
        "lunch"
      ],
      "altText": "Grilled chicken wrap with fries",
      "thumbnailUrl": null,
      "width": 1920,
      "height": 1080,
      "durationSec": null,
      "pdfPageCount": null,
      "loopDurationMs": null,
      "fontFamily": null,
      "fontWeights": null,
      "state": "ready",
      "stateReason": null,
      "stateCode": null,
      "stateFault": null,
      "stateProgress": null,
      "codec": null,
      "playableRev": 0,
      "loopState": null,
      "loopCodecs": null,
      "loopRev": null,
      "loopRotation": null,
      "loopBytes": null,
      "seqState": null,
      "seqCodecs": null,
      "seqRev": null,
      "seqRotation": null,
      "seqBytes": null,
      "seqConform": null,
      "masterKey": null,
      "masterBytes": null,
      "masterProbe": null,
      "rendition4k": null,
      "frameLumaMean": null,
      "frameLumaVariance": null,
      "frameEdgeDensity": null,
      "startsAt": null,
      "expiresAt": null,
      "autoArchiveOnExpiry": false,
      "qr": null,
      "webConfig": null,
      "replayState": null,
      "lastReplayAt": null,
      "lastReplaySuccessAt": null,
      "lastFailedStep": null,
      "lastFailedReason": null,
      "autoCaption": false,
      "captionTrackKey": null,
      "captionState": null,
      "showCaptions": true,
      "audioEnabled": false,
      "focalRegion": null,
      "fit": "contain",
      "autoSmartFit": true,
      "rotation": 0,
      "originalFormat": null,
      "packageEntry": null,
      "packageFiles": null,
      "packageBytes": null,
      "importSourceId": null,
      "nodeId": null,
      "recalledAt": null,
      "recalledBy": null,
      "createdAt": "2026-09-20T10:15:00.000Z",
      "updatedAt": "2026-09-20T10:15:00.000Z",
      "deletedAt": null,
      "usageCount": 2,
      "uploadedByName": "Sam Rivera",
      "uploadSource": "ui"
    }
  ],
  "nextCursor": null,
  "total": 1
}

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/media

Auth: Bearer token. Permission: media.create.

Create a media asset record for a file whose bytes are already stored elsewhere, by providing name, kind, and url. This creates only the metadata record; to upload new file bytes, use POST /v1/media/upload, PUT /v1/media/upload/:uploadId, or POST /v1/media/import-url instead. Notes. - The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column. - Use this for links (web pages, streams, dashboards). To add a FILE, use POST /v1/media/upload, the multipart upload, or POST /v1/media/import-url.

Request body: application/json

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

Response 201: Success.

Response 400: fit is not a known value.

Response 401: Missing, expired or revoked bearer token.

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

Response 404: The folder or location does not exist.

Response 422: name, kind or url is missing, or kind is unknown.

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

GET /v1/media/{id}

Auth: Bearer token. Permission: media.view.

Return one media asset with its full details, including kind, url, dimensions, duration, tags, folder, play window, and web configuration.

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

Response 200: Success.

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 (or it is in the recycle bin).

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

PATCH /v1/media/{id}

Auth: Bearer token. Permission: media.edit.

Edit a media asset. Accepts name, altText, tags, folderId, node, play-window fields (startsAt, expiresAt, autoArchiveOnExpiry), audioEnabled, a QR code overlay, and web configuration. Changing the URL of a web-kind asset re-checks it to make sure it is safe to fetch. Send only the fields to change. state and bytes are set by processing and ignored here. Notes. - The response is the stored row, not the GET shape: it has no usageCount, uploadedByName or uploadSource. - An invalid fit answers 400 with only error (no message); every other validation failure is 422 validation_error.

Request body: application/json

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

Response 200: Success.

Response 400: fit is not one of contain, cover, fill, blur-fill.

Response 401: Missing, expired or revoked bearer token.

Response 403: Moving it to a location where you lack media.edit, or attaching an SSO connection without settings.edit.

Response 404: No such asset in this workspace.

Response 409: conflict: baseUpdatedAt is stale; the body carries current.

Response 422: Invalid kind, URL, folder or location.

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