API Overview

Everything you need to get started with the Mosaic API.

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",
  "scopes": ["agents:read", "agent_runs:read", "triggers:read"]
}

TIP

Always test your API key with /whoami first when setting up a new integration. This catches authentication issues before you start building.

scopes: null means full access; an array lists the explicit permissions. An empty array grants no entity permissions. Configure restricted API keys before giving a key to an AI agent. A read-only key cannot start runs.

For folder-to-run dashboards, start with Pipeline Observability.

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

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 accounts and read post analytics.	Connections, Post, Get Post, Analytics

---

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. If your organization configured an x-api-key value and approved HTTPS origin, matching webhooks include that header as well. 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

Scope restrictions return structured 403 errors with code, required_scope, granted_scopes, retryable: false, and resolution. Agents should report the missing scope to an owner/admin instead of retrying the same key. See API key error examples.

Base URL

https://api.mosaic.so