Media uploads and inspection

Upload reusable images, video, audio and fonts before referencing them from projects and templates.

Multipart upload

curl -X POST "$JSONCUT_API/api/v2/media" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -F "file=@./product-demo.mp4" \
  -F "retention=project" \
  -F "projectId=$PROJECT_ID"

Persist the returned reference, such as jsoncut-media://media_01J..., in project source. Preview URLs are short lived and must not be stored in a template.

Retention

Value	Use
`temporary`	One-shot inline work that may expire.
`project`	Durable media owned by one project. Requires `projectId`.
`template`	Durable media required by a template. Requires `templateId`.
`persistent`	Workspace media not yet attached to a project.

POST /api/v2/media also accepts an application/json body with a Base64 data: URL. This is convenient for tiny generated assets, but the JSON request has a strict size limit. On PAYLOAD_TOO_LARGE, upload multipart media and use the returned reference.

Import a public URL

curl -X POST "$JSONCUT_API/api/v2/media/import-url" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://cdn.example.com/product.jpg","name":"Product photo","kind":"image","mimeType":"image/jpeg","retention":"project","projectId":"'"$PROJECT_ID"'"}'

The importer rejects private-network targets, unsafe redirects, unsupported content and mismatched MIME types.

Inspect metadata

curl -X POST "$JSONCUT_API/api/v2/media/inspect" \
  -H "X-API-Key: $JSONCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mediaId":"media_01J..."}'

Inspection returns useful, safe properties such as dimensions, duration, streams, codec and audio metadata. Use GET /api/v2/media/{id}/content for byte-range playback or download.

Studio resumable uploads are intentionally not public developer endpoints. Server integrations use the bounded upload shown here; MCP Agents can request one-use upload tickets without exposing storage credentials.

Supported public kinds

Public media records use image, video, audio or font. Exact MIME acceptance and request-size limits are part of the live upload media operation. URL import accepts a narrower allowlist than a direct upload and always pins a safe copy.

Inspection result

Inspection can report format, byte size, dimensions, aspect ratio, frame rate, duration, alpha, video codec and audio stream information. Missing metadata stays absent rather than being guessed. Warnings describe a usable file that still deserves attention.

Delete safely

Delete only unused media. A project or template must keep its stable media reference resolvable for preview and rendering. If the API rejects a deletion because the asset is still owned by active work, remove or replace those references first.