Skip to content

Media API ​

Public API · Enterprise Edition

The Media library exposes a public, key-gated surface (/api/media/v1/) for external integrations; the workspace-scoped management routes are part of the internal application API. Both are detailed below. Media is an Enterprise-Edition feature.

The Media API manages binary assets (images, videos, documents) stored in Cloudflare R2 object storage. Assets are processed with Sharp for optimization and variant generation.

There are two surfaces:

  • Application API (this page's main sections) — project-scoped, session-authenticated, used by the Studio SPA:
    /api/workspaces/:workspaceId/projects/:projectId/media/...
  • Public Media API — key-gated external surface (see Public Media API below):
    /api/media/v1/:projectId/assets/...

Enterprise Feature

Media upload and management require the enterprise bridge (ee/) to be loaded and R2 credentials to be configured. The media provider is null in the Community Edition, so every media route returns 503 there. On the managed service the media library is available on Starter plans and above.

Upload Media ​

Upload a file to the project media library.

POST /api/workspaces/:workspaceId/projects/:projectId/media

Request ​

Multipart form data:

FieldTypeRequiredDescription
fileFileYesBinary file to upload
altstringNoAlt text for accessibility
tagsstringNoComma-separated tags
variantsstringNoJSON string describing the variants to generate. Custom variant objects need the media.custom_variants feature, and the number of variants is capped by the plan's media.variants_per_field limit.

Available to workspace owners and admins and to members assigned to the project; needs a plan with media.upload (403 media.upload_upgrade). Other errors: 400 for a missing file field or a disallowed MIME type, 400 media.file_too_large over the plan's file-size cap, 403 storage.quota_exceeded, 503 when no media provider is configured.

Response ​

Status 201 with the created asset:

json
{
  "id": "uuid",
  "filename": "hero-banner.webp",
  "contentType": "image/webp",
  "size": 125000,
  "width": 1920,
  "height": 1080,
  "format": "webp",
  "blurhash": "LEHV6nWB2yk8",
  "alt": "Hero banner image",
  "tags": ["hero", "banner"],
  "originalPath": "media/original/abc123.webp",
  "variants": {
    "thumbnail": {
      "path": "media/thumbnail/abc123.webp",
      "width": 300,
      "height": 169,
      "format": "webp",
      "size": 12000
    }
  },
  "createdAt": "2026-01-01T00:00:00Z"
}

Plan Limits ​

PlanMax File SizeStorageVariants per Field
Free———
Starter10 MB5 GB4
Pro50 MB25 GB10
Enterprise100 MB100 GBUnlimited

Upload from URL ​

Import a media asset from an external URL.

POST /api/workspaces/:workspaceId/projects/:projectId/media/upload-url

Request Body ​

FieldTypeRequiredDescription
urlstringYesSource URL to fetch
altstringNoAlt text
tagsstring[]NoTags for organization
variantsstring | objectNoVariant configuration (same rules as the multipart variants field)

Returns 201 with the created asset. Same access, plan feature (media.upload) and quota rules as a direct upload. The fetch is guarded against requests to private addresses.


List Media ​

List media assets with filtering and pagination.

GET /api/workspaces/:workspaceId/projects/:projectId/media

Query Parameters ​

ParameterTypeDefaultDescription
pagenumber1Page number
limitnumber50Items per page (max 100)
searchstring--Search by filename, alt text
tagsstring--Filter by tags (comma-separated)
typestring--Filter by MIME type prefix (e.g., image)
sortstringnewestSort order: newest, oldest, name, size

Available to workspace owners and admins and to members assigned to the project (403 project.access_denied otherwise); needs the media.library feature (403 media.library_upgrade). Returns 503 when no media provider is configured.

Response ​

json
{
  "assets": [ ... ],
  "total": 42
}

Get Asset ​

Get full metadata for a specific media asset.

GET /api/workspaces/:workspaceId/projects/:projectId/media/:assetId

Same access and plan rules as List Media. 404 media.asset_not_found when the asset belongs to another project.


Preview Asset ​

Get a binary preview of a media asset (serves the file).

GET /api/workspaces/:workspaceId/projects/:projectId/media/:assetId/preview

Optional query parameter variant selects a variant by key; without it the original is served. Responses are private, max-age=3600. SVG files are served inside a sandbox.


Download Source ​

Download the file exactly as it was uploaded (the delivery master may have had metadata such as camera or location stripped).

GET /api/workspaces/:workspaceId/projects/:projectId/media/:assetId/source

Project members only (session). Sent as an attachment, uncached, and never part of public delivery. 404 media.source_not_stored when no source was kept for the asset.


Update Asset Metadata ​

Update alt text, tags, or focal point for an asset.

PATCH /api/workspaces/:workspaceId/projects/:projectId/media/:assetId

Request Body ​

FieldTypeRequiredDescription
altstringNoNew alt text
tagsstring[]NoNew tags
focalPoint{ x: number, y: number }NoFocal point coordinates (0-1 range)

Workspace owner or admin only. 404 media.asset_not_found when the asset belongs to another project. Returns the updated asset.


Delete Asset ​

Delete an asset and all its variants from storage and database.

DELETE /api/workspaces/:workspaceId/projects/:projectId/media/:assetId

Workspace owner or admin only. Returns { "deleted": true }.


Bulk Operations ​

Perform bulk operations on multiple assets.

POST /api/workspaces/:workspaceId/projects/:projectId/media/bulk

Request Body ​

FieldTypeRequiredDescription
action'delete' | 'tag'YesBulk action type
assetIdsstring[]YesAsset IDs to process (max 50, else 400 media.bulk_limit_exceeded)
tagsstring[]For tagTags to add; merged into each asset's existing tags

Workspace owner or admin only. Returns { "results": [{ "id", "success", "error?" }] }; an asset in another project reports success: false.


Bulk Ingest from URLs ​

Import many remote images in one call and get back a map from each source URL to its new delivery URL.

POST /api/workspaces/:workspaceId/projects/:projectId/media/bulk-ingest

Request Body ​

FieldTypeRequiredDescription
items{ url, alt?, tags?, filename? }[]YesUp to 100 items per request
concurrencynumberNoParallel fetches (bounded server-side)
dedupebooleanNoSet false to store a second copy of an identical file; by default identical content is reused

Same access and plan rules as a single upload (media.upload). Limited to 10 requests per minute per user (429). One failing URL is reported in its result and never aborts the batch. The response carries per-item results, succeeded/failed/deduped counts, and a map of source URL to delivery URL.


Rehost Media References ​

Rewrite the media URLs committed in a project's content so they point at this project's delivery URLs (for example after moving a project to another Studio instance or reconnecting its repository as a new project).

POST /api/workspaces/:workspaceId/projects/:projectId/media/rehost

Request Body ​

FieldTypeRequiredDescription
from{ siteUrl: string, projectId: string }YesThe old host and project id the references currently point at
dryRunbooleanNoDefaults to true; report what would change without committing. Pass false for a real run.
copyAssetsbooleanNoAlso copy the old project's media objects and library rows (the caller must be owner or admin of the source project's workspace)

Workspace owner or admin only. A real run commits once; if any referenced asset is missing from this project's storage it commits nothing and returns 409 with the list. Limited to 10 requests per minute per user.


Public Media API (Key-Gated) ​

The public media surface lets agents and CI authenticate with a CDN/media API key instead of a session. It is gated by CDN keys carrying the right scope:

http
Authorization: Bearer crn_live_your-api-key

Auth model (per request): Bearer key validation → the key's project must match :projectId → scope check → per-key hourly rate limit → plan feature → media provider. The project must have CDN enabled (cdn_enabled, else 403 cdn.not_enabled); read routes require the media:read scope and the media.library feature. Write routes require the media:write scope; POST /assets additionally needs the media.upload feature, while PATCH, DELETE and bulk need media.library. API uploads are attributed to the workspace owner. Returns 503 when no media provider is configured.

MethodPathScope
GET/api/media/v1/:projectId/assetsmedia:read
POST/api/media/v1/:projectId/assetsmedia:write
GET/api/media/v1/:projectId/assets/:assetIdmedia:read
PATCH/api/media/v1/:projectId/assets/:assetIdmedia:write
DELETE/api/media/v1/:projectId/assets/:assetIdmedia:write
POST/api/media/v1/:projectId/assets/bulkmedia:write

List (GET /assets) ​

Query parameters: search, tags (comma-separated), type (MIME prefix), limit (default 50, max 100), page, sort (newest, oldest, name, size). Returns { assets, total }.

Upload (POST /assets) ​

Accepts either multipart/form-data with a file part (plus optional alt, tags, variants) or a JSON body { url, alt?, tags?, variants? } for URL import (SSRF-guarded). Returns 201 with the created asset. Public responses add url and variantUrls (delivery URLs) to each asset and never include the stored source. The variants field behaves as on the application upload route.

Get / Update / Delete (/assets/:assetId) ​

GET returns the asset. PATCH updates alt, tags, and/or focalPoint. DELETE removes the asset and its variants, returning { "deleted": true }.

Bulk (POST /assets/bulk) ​

json
{
  "action": "delete",
  "assetIds": ["uuid1", "uuid2"]
}

action is delete or tag (the latter also requires a tags array). Capped at 50 asset IDs per call; assets outside the key's project are silently skipped. Returns { action, affected }.

Released under the AGPL-3.0 License. Privacy