What is the Mosaic API?
The Mosaic API lets you run video editing workflows entirely from code. A workflow is called an Agent — a graph of processing steps (called Tiles) that can do anything from adding captions to generating clips to full multi-step pipelines. You supply a video, Mosaic does the work and returns the result.
Getting Started
1. Get your API key
Create an API key in your Mosaic dashboard. All keys are prefixed with mk_ and authenticate via the Authorization: Bearer header.
curl -H "Authorization: Bearer mk_your_key" \
-H "Content-Type: application/json" \
https://api.mosaic.so/whoami
2. Verify with Who Am I
Call /whoami to confirm your key is valid and see which organization it belongs to:
{
"organization_id": "123e4567-e89b-12d3-a456-789012345678",
"organization_name": "Acme Productions",
"organization_slug": "acme-productions",
"created_at": "2024-01-15T08:00:00Z",
"last_used_at": "2024-01-15T14:30:00Z"
}
Always test your API key with /whoami first when setting up a new integration. This catches authentication issues before you start building.
3. Run your first agent
The typical flow is three steps:
- Run an agent —
POST /agent/{agent_id}/run with your video URLs and optional parameters.
- Track progress — Poll
GET /agent_run/{run_id} or subscribe to a webhook via callback_url.
- Download outputs — Outputs (signed video URLs, thumbnails, Premiere timelines) are included in the run response.
Core Concepts
| Concept | What it is | Key endpoints |
|---|
| Agents | Reusable video editing workflows you create and configure. Each agent is a graph of tiles. | Create, Update, List |
| Agent Runs | An execution of an agent against one or more input videos. | Run, Get Status, Get Nodes |
| Avatar Profiles | Reusable AI Avatar identities created from a one-person source video, or an image plus clean single-speaker voice reference from the same person. | Create, Get, List |
| Node Types | The catalog of available tiles (Captions, Reframe, Clips, etc.) and their parameters. | List Types, Get Type |
| Triggers | Automatic run triggers — YouTube channel monitors, schedules, or storage watchers. | List, Add YouTube |
| Webhooks | Real-time POST notifications for run lifecycle events (RUN_STARTED, RUN_PROGRESS, RUN_FINISHED). | Events |
| Asset Management | Upload your own video, audio, and image files for use in agent runs. | Upload Flow |
| Credits | Check balance, view usage history, and configure auto top-up. | Balance, Usage |
| Plans | View your current plan and upgrade. | Get Plan, Upgrade |
| Social | Publish outputs directly to connected social platforms. | Post, Track |
Authentication
Use your API key with the Authorization: Bearer header on every request.
curl -H "Authorization: Bearer mk_your_key" \
-H "Content-Type: application/json" \
https://api.mosaic.so/agent/[agent_id]/run
Webhook Authentication
When a webhook secret is configured for your account, Mosaic includes an X-Mosaic-Signature header for verification. Always validate this signature before processing webhook payloads. See the Webhook Events documentation for details.
Error Handling
Responses use conventional HTTP status codes. On errors the body contains a detail field with a human-readable message.
{
"detail": "Invalid request body: video_urls: Required"
}
| Status | Meaning | Typical Cause |
|---|
| 400 | Bad Request | Malformed JSON, missing required field, or invalid value |
| 401 | Unauthorized | API key is missing, revoked, or invalid |
| 403 | Forbidden | API key does not have access to the requested resource |
| 404 | Not Found | Agent, run, or agent_node_id does not exist |
| 413 | Payload Too Large | Uploaded file exceeds the size limit or video exceeds duration limit |
| 500 | Internal Server Error | Unexpected server-side exception |
Base URL
