---
title: "Update a media asset"
method: PATCH
path: "/v1/media/{id}"
tags: ["media"]
---

# Update a media asset

`PATCH /v1/media/{id}`

## Request

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

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

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string
  - `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'
  - `url` string: An https URL, a /v1/ path or a data:image URI; for a web link, the page address (private and internal network addresses are refused).
  - `active` boolean: False archives the asset.
  - `folderId` string, nullable
  - `tags` string[]
  - `altText` string, nullable
  - `thumbnailUrl` string, nullable
  - `width` integer, nullable
  - `height` integer, nullable
  - `durationSec` number, nullable
  - `startsAt` string, nullable
  - `expiresAt` string, nullable
  - `autoArchiveOnExpiry` boolean
  - `qr` object, nullable
  - `webConfig` object, nullable
  - `nodeId` string, nullable: Move to another location (needs media.edit there).
  - `audioEnabled` boolean
  - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill'
  - `baseUpdatedAt` string: The `updatedAt` your edit is based on. When set and the row has moved since, the write is refused with 409 and the current row.

## Response `200`

Success.

- object
  - `data` MediaAssetUpdated, required: The stored row after a PATCH, without the list-only fields.
    - `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).

## Other responses

- `400`: `fit` is not one of contain, cover, fill, blur-fill.
- `401`: Missing, expired or revoked bearer token.
- `403`: Moving it to a location where you lack media.edit, or attaching an SSO connection without settings.edit.
- `404`: No such asset in this workspace.
- `409`: `conflict`: `baseUpdatedAt` is stale; the body carries `current`.
- `422`: Invalid kind, URL, folder or location.
- `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)