​
Overview

Mosaic’s REST API allows you to kick off professional-grade video editing workflows (“Agents”) entirely from code. An agent is a pre-built graph of AI and rendering nodes that can do anything from audio enhancement to animated captions – you supply a video and optional parameters, Mosaic returns a polished result.

​
Typical flow

  1. Upload a video – Get a signed URL and PUT the bytes (/video/get-upload-url, /video/finalize-upload).
  2. Run an agent – Call /run-agent with the file_id you just created.
  3. Track progress – Poll /get-agent-run-simple/{id} or subscribe to a webhook.
  4. Download outputs – Fetch signed URLs via /get-agent-run-outputs/{id}.
Grab the full walk-through in the Quickstart.

​
Authentication

Mosaic supports two flavours of authentication:

​
1. API Keys (Production traffic)

Use an API key prefixed mk_ for all operational endpoints (/run-agent, polling status, downloading outputs etc.). 
# Bearer header
curl -H "Authorization: Bearer mk_your_key" \
     -H "Content-Type: application/json" \
     https://api.usemosaic.ai/api/run-agent

# X-API-Key header (alternative)
curl -H "X-API-Key: mk_your_key" \
     -H "Content-Type: application/json" \
     https://api.usemosaic.ai/api/run-agent

​
2. Session Tokens (Developer Portal)

When you log in to the Mosaic dashboard you receive a short-lived JWT issued by Supabase. Use this to manage API keys and check your credit balance under the /api/dev namespace.

​
Rate Limiting & Quotas

PlanConcurrent RunsUpload SizeFree Credits
Pro1010 GiB20 000
Enterprisecustomcustomcustom
Additional request-per-minute limits only apply to developer-portal endpoints.

​
Error Handling

Responses use conventional HTTP status codes. On errors the body contains a machine-readable error field plus a human friendly detail. 
{
  "detail": "Too many concurrent runs",
  "error": "concurrent_agent_limit"
}
StatusError CodeTypical Cause
400validation_errorMalformed JSON or missing field
401invalid_api_keyKey revoked / wrong value
403concurrent_agent_limit> 10 running agents (Free plan)
403insufficient_creditsBalance too low
404not_foundUnknown ID
422parameter_out_of_rangeField outside validation bounds
429rate_limit> 120 requests / min to /api/dev/*
500internal_server_errorUnexpected exception

​
Base URL

https://api.usemosaic.ai/api