---
title: "List media"
method: GET
path: "/v1/media"
tags: ["media"]
---

# List media

`GET /v1/media`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/media`
- Auth: HTTP bearer

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.

## Query parameters

- `search` string
- `kind` string
- `state` string
- `folderId` string
- `usableAt` string
- `limit` integer
- `cursor` string
- `count` '1'

## Response `200`

Success.

- object
  - `data` MediaAsset[], required
    - `id` string, required: Media asset id.
    - `spaceId` string, required: Workspace id.
    - `name` string, required
    - `kind` string, required: Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value.
    - `url` string, required: Where the bytes live: a `/v1/media/<id>/file` path, an `https` URL, `r2://…`, or (for a web link) the page address.
    - `bytes` integer, required: Stored size in bytes (0 for links and apps).
    - `checksum` string, nullable, required
    - `active` boolean, required: False when archived.
    - `folderId` string, nullable, required
    - `tags` unknown, required
    - `altText` string, nullable, required
    - `thumbnailUrl` string, nullable, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `durationSec` number, nullable, required: Video/audio length in seconds.
    - `pdfPageCount` integer, nullable, required
    - `loopDurationMs` integer, nullable, required: Animated image loop length.
    - `fontFamily` string, nullable, required
    - `fontWeights` unknown, required
    - `state` string, required: Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …
    - `stateReason` string, nullable, required
    - `stateCode` string, nullable, required
    - `stateFault` 'user' | 'platform', nullable, required
    - `stateProgress` integer, nullable, required
    - `codec` string, nullable, required
    - `playableRev` integer, required: Bumped whenever the playable bytes change.
    - `loopState` 'queued' | 'ready' | 'failed', nullable, required
    - `loopCodecs` string, nullable, required
    - `loopRev` integer, nullable, required
    - `loopRotation` integer, nullable, required
    - `loopBytes` integer, nullable, required
    - `seqState` 'queued' | 'ready' | 'failed', nullable, required: Playlist-sequencer rendition state (video only; minted when the video plays in a run of consecutive videos).
    - `seqCodecs` string, nullable, required
    - `seqRev` integer, nullable, required
    - `seqRotation` integer, nullable, required
    - `seqBytes` integer, nullable, required
    - `seqConform` integer, nullable, required
    - `masterKey` string, nullable, required
    - `masterBytes` integer, nullable, required
    - `masterProbe` string, nullable, required
    - `rendition4k` string, nullable, required
    - `frameLumaMean` number, nullable, required
    - `frameLumaVariance` number, nullable, required
    - `frameEdgeDensity` number, nullable, required
    - `startsAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `expiresAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `autoArchiveOnExpiry` boolean, required
    - `qr` unknown, required
    - `webConfig` unknown, required
    - `replayState` 'healthy' | 'replay_pending' | 'replay_failed', nullable, required
    - `lastReplayAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `lastReplaySuccessAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `lastFailedStep` integer, nullable, required
    - `lastFailedReason` string, nullable, required
    - `autoCaption` boolean, required
    - `captionTrackKey` string, nullable, required
    - `captionState` 'pending' | 'ready' | 'failed', nullable, required
    - `showCaptions` boolean, required
    - `audioEnabled` boolean, required
    - `focalRegion` string, nullable, required: Smart-fit focal region, as stored JSON text.
    - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill', required: How the asset fills a box.
    - `autoSmartFit` boolean, required
    - `rotation` integer, required: Clockwise rotation in degrees.
    - `originalFormat` string, nullable, required
    - `packageEntry` string, nullable, required
    - `packageFiles` integer, nullable, required
    - `packageBytes` integer, nullable, required
    - `importSourceId` string, nullable, required
    - `nodeId` string, nullable, required: Home location; null = workspace library root.
    - `recalledAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `recalledBy` string, nullable, required
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).
    - `deletedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `usageCount` integer, required: Playlists, schedules, layouts, creatives, boards and screens that use this asset.
    - `uploadedByName` string, nullable, required: Who uploaded it, from the audit log.
    - `uploadSource` 'ui' | 'api' | 'mcp', nullable, required: How it was uploaded.
  - `nextCursor` string, nullable: Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.
  - `total` integer: Total matching rows, when the route computes it.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)