Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. Run an agent — POST /agent/{agent_id}/run with your video URLs and optional parameters.
  2. Track progress — Poll GET /agent_run/{run_id} or subscribe to a webhook via callback_url.
  3. Download outputs — Outputs (signed video URLs, thumbnails, Premiere timelines) are included in the run response.

​
Core Concepts

ConceptWhat it isKey endpoints
AgentsReusable video editing workflows you create and configure. Each agent is a graph of tiles.Create, Update, List
Agent RunsAn execution of an agent against one or more input videos.Run, Get Status, Get Nodes
Node TypesThe catalog of available tiles (Captions, Reframe, Clips, etc.) and their parameters.List Types, Get Type
TriggersAutomatic run triggers — YouTube channel monitors, schedules, or storage watchers.List, Add YouTube
WebhooksReal-time POST notifications for run lifecycle events (RUN_STARTED, RUN_PROGRESS, RUN_FINISHED).Events
Asset ManagementUpload your own video, audio, and image files for use in agent runs.Upload Flow
CreditsCheck balance, view usage history, and configure auto top-up.Balance, Usage
PlansView your current plan and upgrade.Get Plan, Upgrade
SocialPublish 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
API keys can be created and managed in your Mosaic dashboard.

​
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"
}
StatusMeaningTypical Cause
400Bad RequestMalformed JSON, missing required field, or invalid value
401UnauthorizedAPI key is missing, revoked, or invalid
403ForbiddenAPI key does not have access to the requested resource
404Not FoundAgent, run, or agent_node_id does not exist
413Payload Too LargeUploaded file exceeds the size limit or video exceeds duration limit
500Internal Server ErrorUnexpected server-side exception

​
Base URL

https://api.mosaic.so