---
title: "Import media from a URL"
method: POST
path: "/v1/media/import-url"
tags: ["media"]
---

# Import media from a URL

`POST /v1/media/import-url`

## Request

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

Import a file from a remote URL into the media library. The API fetches the file server-side, checking that the URL does not point to a disallowed destination, stores its bytes, and creates the media asset record. This is the same path used by the upload_media_from_url tool.

Fetches a public http(s) URL into the library. SVG is refused.

**Notes.**
- The response is the row as built for insert, not the GET shape: `tags` is a JSON string (not an array), `sourceUrl` is present but not stored, and most columns (state, fit, width, …) are absent. Read GET /v1/media/{id} for the settled asset.

## Request body

- object
  - `url` string, required: Public http(s) address of the file.
  - `name` string: Display name; defaults to the file name in the URL.
  - `folderId` string
  - `nodeId` string: Home location; defaults to your own.
  - `tags` string[]
  - `autoCaption` boolean: Videos: generate captions.
  - `autoSmartFit` boolean: Images: detect a focal region (default true).

## Response `201`

Success.

- object
  - `data` ImportedMedia, required: The row created by an import, before processing settles.
    - `id` string, required: Media asset id.
    - `spaceId` string, required
    - `name` string, required
    - `kind` string, required
    - `url` string, required: `/v1/media/<id>/file`.
    - `bytes` integer, required
    - `checksum` string, nullable, required
    - `active` true, required
    - `folderId` string, nullable, required
    - `nodeId` string, nullable, required
    - `tags` string, required: JSON-encoded array of strings — NOT decoded here, unlike GET /v1/media.
    - `sourceUrl` string, required: The URL that was imported. Not stored; returned by this route only.
    - `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`).
- `413`: `too_large`: the file is over the size limit for its kind.
- `415`: `unsupported_type`: SVG or an unknown content type.
- `422`: Missing or non-http URL, a blocked address (`url_blocked`), or an unknown folder or location.
- `502`: `fetch_failed` / `source_status`: the source did not answer with the file.
- `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)