MOmosaic
Agents

Run an agent

Execute an agent workflow. Supports standard video-input workflows and generation-only workflows (AI Avatar, Video Generation, Audio Generation, or Image Generation). Canonical input model is video_inputs (per Video Input tile). Top-level input arrays (video_ids, node_render_ids, video_urls) are shorthand for single-input runs. Do not mix top-level input arrays with video_inputs in the same request.

post/agent/{agent_id}/run

Request

  • Base URL
    https://api.mosaic.so
  • URL
    https://api.mosaic.so/agent/{agent_id}/run
  • Auth
    • HTTP bearer
    • or API key in header X-API-Key

Path parameters

agent_idstring required

The ID of the agent to run

Request body

video_idsstring[]

Top-level shorthand for single-input runs. Video UUIDs from the Uploads API (or existing workspace video assets).

node_render_idsstring[]

Top-level shorthand for single-input runs. Completed agent_node_render IDs from prior run outputs (GET /agent_run/{run_id} -> outputs[].id) or run webhooks.

video_urlsstring[]

Top-level shorthand for single-input runs. Video URLs to ingest (including YouTube and signed HTTP/HTTPS URLs). YouTube videos max 5 hours, signed URLs max 5 hours / 5 GB per input.

callback_urlstring uri

Optional webhook URL for status updates

update_paramsobject

Optional parameters to override node parameters in the agent workflow. Key is agent_node_id, value is parameter object. Parameters are validated against each node's schema; invalid node IDs/values return 400 and the run is not created.

ignore_nodesstring[]

Optional list of agent_node_id values to bypass for this run. Ignored nodes are removed from the runtime graph and their incoming edges are rewired directly to their downstream nodes.

Response

Agent run started successfully

run_idstring

Unique identifier for this agent run

Changes

No recorded changes to this operation across all 1 revision of this API.