---
title: "Create a media item"
method: POST
path: "/v1/media"
tags: ["media"]
---

# Create a media item

`POST /v1/media`

## Request

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

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

- object
  - `name` string, required
  - `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', required
  - `url` string, required: An https URL, a /v1/ path, or (for a web link) the page address. Private and internal network addresses are refused.
  - `active` boolean
  - `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: Web link settings (refresh, zoom, …).
  - `nodeId` string, nullable: Home location. Default: the caller's own location.
  - `audioEnabled` boolean
  - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill'

## Response `201`

Success.

- object
  - `data` object, 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).
    - `active` boolean, required: False when archived.
    - `tags` unknown, required
    - `state` string, required: Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …
    - `autoArchiveOnExpiry` boolean, required
    - `nodeId` string, nullable: Home location; null = workspace library root.
    - `folderId` string, nullable
    - `altText` string, nullable
    - `thumbnailUrl` string, nullable
    - `width` integer, nullable
    - `height` integer, nullable
    - `durationSec` number, nullable: Video/audio length in seconds.
    - `startsAt` string, nullable: ISO-8601 timestamp (UTC).
    - `expiresAt` string, nullable: ISO-8601 timestamp (UTC).
    - `qr` unknown
    - `webConfig` unknown
    - `audioEnabled` boolean
    - `fit` 'contain' | 'cover' | 'fill' | 'blur-fill': How the asset fills a box.
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).
    - `deletedAt` unknown, required

## Other responses

- `400`: `fit` is not a known value.
- `401`: Missing, expired or revoked bearer token.
- `403`: The token lacks the permission this operation needs (see `x-brix-permission`).
- `404`: The folder or location does not exist.
- `422`: `name`, `kind` or `url` is missing, or `kind` is unknown.
- `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)