canonical: https://jentic.com/apis/mosaic.so/mosaic # Mosaic So Mosaic AI API The Mosaic AI API builds and runs AI video editing workflows, called agents, made of node types such as video inputs, AI avatar, video generation, audio generation, and image generation tiles. A run takes video_inputs, uploaded video IDs, or video URLs, reports per-node status, can be resumed or cancelled, and can send status updates to a callback_url. Agents can also be triggered by new uploads on watched YouTube channels. Finished clips can be published or scheduled to connected X, LinkedIn, Instagram, Facebook, TikTok, and YouTube accounts, with per-post analytics and comments, and shared stores hold reusable key-value entries for workflows. ## For AI agents Create and run Mosaic AI video editing agents on uploaded or linked videos, track each run's nodes, and publish or schedule the results to connected social accounts with post analytics. ## Scope Does not stream live video, host a video player, or sell ad placements. Use for running Mosaic AI video editing workflows and publishing their output only. ## Capabilities - Run a Mosaic video editing agent on video_inputs, uploaded video_ids, or video_urls, with an optional callback_url - Track a run's status and per-node progress, then resume or cancel it - Upload video, audio, and image files through signed upload URLs and finalize them for use in runs - Trigger an agent automatically from new uploads on watched YouTube channels - Publish or schedule a post with media_urls to X, LinkedIn, Instagram, Facebook, TikTok, or YouTube - Read analytics and comments for a published social post - Store reusable entries in shared stores, with bulk upsert of up to 5000 entries per call ## Use cases ### AI content agent that edits and publishes clips A content agent can turn a long recording into short clips and post them without a developer wiring Mosaic's upload, run, and publish steps by hand. Through Jentic the agent searches for 'run a Mosaic video agent', loads the run operation with its input schema, and passes the video URL. Your own Jentic One instance attaches the API key at call time, and the agent polls the run, then posts the result to the connected accounts. Example prompt: Call POST `/agent/{agent_id}/run` with video_urls containing the recording link, poll GET `/agent_run/{run_id}` until it completes, then call POST `/social/post` with the output in media_urls and platforms tiktok and youtube ### Editing every new upload from a YouTube channel Creators who publish long-form video on YouTube can have Mosaic process each new upload automatically. Adding YouTube channel listeners to an agent's triggers starts a run whenever the channel publishes, and the agent's run history can be filtered by status and date range to review what was produced. Example prompt: Call POST `/agent/{agent_id}/triggers/add_youtube_channels` with youtube_channels set to the channel ID, then list GET `/agent/{agent_id}/runs` with status completed to review the outputs ### Uploading source media for a run Local files reach Mosaic through a two-step upload: request a signed upload URL for a video, audio, or image file, upload the file to it, and finalize it with the returned ID. The finalized video_id can then be passed to an agent run. Example prompt: Call POST `/uploads/video/get_upload_url`, upload the file to the returned URL, call POST `/uploads/video/finalize_upload` with the video_id, then run the agent with video_ids containing it ### Tracking how published clips perform After clips go out, a social team wants engagement numbers and audience reactions in one place. Mosaic lists posts by status, platform, or social_connection_id, and returns analytics and comments for each post on a connected account. Queued posts can be rescheduled with a new schedule_date or deleted before they publish. Example prompt: Call GET `/social/posts` with platform linkedin, then GET `/social/post/{post_id}/analytics` for each post with its social_connection_id, and report the top performer ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/agent/{agent_id}/run` | Run an agent | | GET | `/agent_run/{run_id}` | Get agent run status | | POST | `/agent/create` | Create an agent | | POST | `/uploads/video/get_upload_url` | Get video upload URL | | POST | `/agent/{agent_id}/triggers/add_youtube_channels` | Add YouTube channel listeners | | POST | `/social/post` | Create social post | | GET | `/social/post/{post_id}/analytics` | Get social post analytics | ## Key resources - **Agents** — Video editing workflows: create, update, duplicate, share, delete, and run - **Agent runs** — Run status, per-node progress, resume, and cancel - **Node types** — The workflow tile types an agent can be built from - **Uploads** — Signed upload URLs and finalize steps for video, audio, and image files - **Social** — Connected accounts, published and scheduled posts, analytics, and comments - **Shared stores** — Key-value stores with entries for reuse across workflows ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 61 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 51 / 100 - Developer Experience & Jentic Compatibility: 64 / 100 - AI-Readiness & Agent Experience: 51 / 100 - Agent Usability: 93 / 100 - Security: 55 / 100 - AI Discoverability: 75 / 100 - **View full report:** https://jentic.com/apis/mosaic.so/mosaic/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Mosaic by hand means choosing bearer or X-API-Key auth, chaining the signed upload and finalize steps before a run, and handling run polling or a callback. Through Jentic you install once, import Mosaic from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Mosaic puts the agent id in the URL path, as in `/agent/{agent_id}/run`, so a rule can hold your agent to one editing workflow and the operations you pick. You choose the operations it may call, so destructive or public ones like deleting an agent or publishing a social post are not included unless you add them. - **Credential handling:** Your Mosaic API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'run a video editing agent' or 'schedule a social post', and Jentic returns the matching Mosaic operation with its input schema, including video_inputs, callback_url, and platforms. ## Related APIs - **Shotstack API** — Template-driven video rendering from JSON edit timelines - **Creatomate API** — Video and image generation from templates - **HeyGen API** — AI avatar video generation - **Buffer API** — Social media scheduling across accounts ## FAQ ### What authentication does the Mosaic AI API use? Per its OpenAPI spec, most Mosaic AI API operations accept either a bearer API key in the Authorization header or the same key in the X-API-Key header. The shared-stores operations declare bearer authentication only, and GET `/social/connect/{connect_token}`, the link an end user opens to connect a social account, needs no key. Through Jentic the key is stored by your own Jentic One instance and attached at call time. ### Can I get Mosaic agent run status updates without polling? Yes. POST `/agent/{agent_id}/run` accepts an optional callback_url, a webhook URL that receives status updates for the run. You can also poll GET `/agent_run/{run_id}` for status and GET `/agent_run/{run_id}/nodes` for per-node progress. ### What are the rate limits for the Mosaic AI API? The OpenAPI spec does not specify rate limits. Check the Mosaic documentation at https://docs.mosaic.so for current limits. ### Is there a Mosaic MCP server? You don't need an MCP server to give your agent Mosaic. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent runs video agents and publishes posts on demand without another server's tool definitions in its context. ### Can I limit what my agent is allowed to do with the Mosaic AI API? Yes. Write a rule that allows only POST `/agent/{agent_id}/run` and GET `/agent_run/{run_id}` for your clip agent's id, so the agent can run that workflow and check on it but cannot publish to social accounts, delete agents, or remove connections. Every call it makes is logged. ### How do I schedule a clip to social media through Jentic? Search Jentic for 'schedule a social post with Mosaic', load the POST `/social/post` operation, and execute it with post text, media_urls, platforms or destinations from GET `/social/connections`, and a future schedule_date. To run it on your own infrastructure, install Jentic One from its GitHub repo.