Overview
Mosaic’s REST API allows you to kick off video editing workflows (“Agents”) entirely from code. An agent is a pre-built graph that can do anything from audio enhancement to animated captions – you supply a video and optional parameters, Mosaic returns the result.
Typical flow
- Run an agent – Call
/agent/[agent_id]/run with video_urls (supports YouTube URLs and signed URLs).
- Track progress – Poll
/agent_run/[run_id] or subscribe to a webhook.
- Download outputs – The outputs are included in the agent run status response.
Explore each endpoint category in the sections below.
Authentication
Use an API key prefixed mk_ for all API endpoints with the Authorization Bearer header.
curl -H "Authorization: Bearer mk_your_key" \
-H "Content-Type: application/json" \
https://api.mosaic.so/agent/[agent_id]/run
Validating Your API Key
Use the /whoami endpoint to verify your API key is working correctly and get information about the associated organization:
curl -X GET "https://api.mosaic.so/whoami" \
-H "Authorization: Bearer mk_your_api_key"
{
"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"
}
- Verifying your API key is valid and active
- Checking which organization the key belongs to
- Confirming the key’s creation and last usage timestamps
- Testing your authentication setup before making other API calls
Always test your API key with /whoami first when setting up a new integration. This helps catch authentication issues early.
Webhook Authentication
When a webhook secret is configured for your account, Mosaic includes an X-Mosaic-Signature header for verification. If configured, 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
