---
title: "Upload a media file"
method: POST
path: "/v1/media/upload"
tags: ["media"]
---

# Upload a media file

`POST /v1/media/upload`

## Request

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

Upload a file in a single request using multipart form data. Accepts form fields file (required), and optional name, nodeId, and folderId. This stores the file and creates the media asset record in one step, and is safe to retry with the same Idempotency-Key header. For large files or programmatic clients, minting an upload URL and then uploading with PUT is usually simpler.

**Notes.**
- Form fields other than `file` are strings, as multipart sends them.
- For files over ~100 MB use the multipart upload.

## Response `201`

Success.

- object
  - `data` UploadedMedia, required: The media row an upload creates, before processing settles.
    - `id` string, required: Media asset id.
    - `spaceId` string, required: Workspace id.
    - `nodeId` string, nullable, required: Home location; null = workspace library root.
    - `folderId` string, nullable, required
    - `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, required: SHA-256 of the bytes.
    - `active` boolean, required: False when archived.
    - `altText` string, nullable, required
    - `width` integer, nullable, required
    - `height` integer, nullable, required
    - `durationSec` number, nullable, required: Video/audio length in seconds.
    - `loopDurationMs` integer, nullable, required: Animated image loop length.
    - `fontFamily` string, nullable, required
    - `fontWeights` integer[], nullable, required: Font files: the weights in the file.
    - `state` 'ready' | 'failed' | 'processing' | 'ready_with_warnings' | 'needs_action', required
    - `stateReason` string, nullable, required
    - `stateCode` string, nullable, required
    - `stateFault` 'user' | 'platform', nullable, required
    - `codec` string, nullable, required
    - `frameLumaMean` number, nullable, required
    - `frameLumaVariance` number, nullable, required
    - `frameEdgeDensity` number, nullable, required
    - `autoCaption` boolean, required
    - `captionState` 'pending', nullable, required
    - `autoSmartFit` boolean, required
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).
    - `deletedAt` unknown, required

## Other responses

- `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.
- `413`: The file is over the limit for its kind (images 250 MB, video 2 GB, documents 100 MB, fonts 10 MB).
- `415`: SVG, or a type the library does not take.
- `422`: `file` is missing.
- `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)