> ## 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. # 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](https://edit.mosaic.so). All keys are prefixed with `mk_` and authenticate via the `Authorization: Bearer` header. ```bash theme={null} 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: ```json theme={null} { "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](/api/webhooks/events) 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**](/api/agents/creating-agents) | Reusable video editing workflows you create and configure. Each agent is a graph of tiles. | [Create](/api/agents/post-agent-create), [Update](/api/agents/post-agent-update), [List](/api/agents/get-agents) | | [**Agent Runs**](/api/agent-runs/post-agent-run) | An execution of an agent against one or more input videos. | [Run](/api/agent-runs/post-agent-run), [Get Status](/api/agent-runs/get-agent-run), [Get Nodes](/api/agent-runs/get-agent-run-nodes) | | [**Avatar Profiles**](/api/avatar-profiles/create-avatar-profile) | 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](/api/avatar-profiles/create-avatar-profile), [Get](/api/avatar-profiles/get-avatar-profile), [List](/api/avatar-profiles/get-avatar-profiles) | | [**Node Types**](/api/agent-nodes/get-agent-nodes) | The catalog of available tiles (Captions, Reframe, Clips, etc.) and their parameters. | [List Types](/api/agent-nodes/get-agent-nodes), [Get Type](/api/node-types/get-node-type) | | [**Triggers**](/api/triggers/get-agent-triggers) | Automatic run triggers — YouTube channel monitors, schedules, or storage watchers. | [List](/api/triggers/get-agent-triggers), [Add YouTube](/api/triggers/post-add-youtube-channels) | | [**Webhooks**](/api/webhooks/events) | Real-time POST notifications for run lifecycle events (`RUN_STARTED`, `RUN_PROGRESS`, `RUN_FINISHED`). | [Events](/api/webhooks/events) | | [**Asset Management**](/api/asset-management/upload-flow) | Upload your own video, audio, and image files for use in agent runs. | [Upload Flow](/api/asset-management/upload-flow) | | [**Credits**](/api/credits/get-credits) | Check balance, view usage history, and configure auto top-up. | [Balance](/api/credits/get-credits), [Usage](/api/credits/get-credits-usage) | | [**Plans**](/api/plan/get-plan) | View your current plan and upgrade. | [Get Plan](/api/plan/get-plan), [Upgrade](/api/plan/post-plan-upgrade) | | [**Social**](/api/social/post-social-post) | Publish outputs directly to connected social accounts and read post analytics. | [Connections](/api/social/get-social-connections), [Post](/api/social/post-social-post), [Get Post](/api/social/get-social-post), [Analytics](/api/social/get-social-post-analytics) | *** ## Authentication Use your API key with the `Authorization: Bearer` header on every request. ```bash theme={null} 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](https://edit.mosaic.so). ### 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](/api/webhooks/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. ```json theme={null} { "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 ```text theme={null} https://api.mosaic.so ```