Skip to main content
POST
/
agent
/
{agent_id}
/
run
Run Agent
curl --request POST \
  --url https://api.example.com/agent/{agent_id}/run
Execute an agent workflow. Supports standard video-input workflows and AI-only workflows (AI Content Generation or AI Avatar).

​
Canonical input model

Treat video_inputs as the canonical run input shape:
  • video_inputs[] entries map assets to a specific Video Input tile (agent_node_id)
  • each entry accepts one or more sources: video_ids, node_render_ids, video_urls
Top-level fields (video_ids, node_render_ids, video_urls) are shorthand for single-input runs.

​
Single-input shorthand

If your runnable graph has one Video Input tile, you can send top-level input arrays without specifying agent_node_id. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'
Example using video_ids (from the Uploads API): 
{
  "video_ids": [
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  ],
  "callback_url": "https://your-webhook.com/callback"
}
Example using node_render_ids (from previous run outputs): 
{
  "node_render_ids": [
    "7ba7b810-9dad-11d1-80b4-00c04fd430c8"
  ],
  "callback_url": "https://your-webhook.com/callback"
}

​
Multi-input workflows

If your agent has multiple runnable Video Input tiles, you must use video_inputs and provide an entry for each runnable input tile. In that mode, do not also send top-level input arrays. You can get each agent_node_id from GET /agent/[agent_id] or from the Mosaic editor’s API info panel for that tile. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_inputs": [
      {
        "agent_node_id": "11111111-1111-1111-1111-111111111111",
        "video_ids": ["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"]
      },
      {
        "agent_node_id": "22222222-2222-2222-2222-222222222222",
        "video_urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]
      }
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
AI-Only Workflows

For workflows starting with AI Content Generation or AI Avatar nodes (and no Video Input node), no video inputs should be provided. These agents generate video content based on the parameters configured in the agent. 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-webhook.com/callback",
    "update_params": {
      "NODE_ID": {
        "prompt": "A futuristic city in the style of cyberpunk"
      }
    }
  }'

​
Parameters

FieldTypeRequiredDescription
video_inputsobject[]ConditionalCanonical per-tile input mapping. Each entry must include agent_node_id plus at least one of video_ids, node_render_ids, video_urls, or mimir_assets. Required for multi-input runs.
video_idsstring[]ConditionalTop-level shorthand for single-input runs. Video UUIDs from the Uploads API (or existing workspace video assets).
node_render_idsstring[]ConditionalTop-level shorthand for single-input runs. Render IDs from prior run outputs (GET /agent_run/{run_id} -> outputs[].id) or run webhooks.
video_urlsstring[]ConditionalTop-level shorthand for single-input runs. Video URLs to ingest (YouTube and signed URLs).
mimir_assetsobject[]ConditionalMimir assets to ingest. Each object has id (Mimir item UUID) and optional artifact (highres, proxy, or auto; defaults to highres). Requires a Mimir connection.
callback_urlstringOptional webhook URL for status updates
update_paramsobjectOptional parameters to override node parameters in the agent workflow. Keys must be valid agent_node_id values from the runnable graph.
ignore_nodesstring[]Optional list of agent_node_id values to bypass for this run. Mosaic removes each ignored node from the runtime graph and rewires incoming edges directly to its downstream nodes.
Input rules:
  • Use either top-level input arrays or video_inputs (not both in the same request).
  • If the runnable graph has multiple Video Input tiles, provide one video_inputs entry for each runnable input tile.
  • node_render_ids are valid video inputs (top-level shorthand for single-input runs, or per-entry in video_inputs).
  • mimir_assets can be combined with other input types in the same entry.
ID source rules:
  • video_ids come from the Uploads API.
  • node_render_ids come from previous run outputs (GET /agent_run/{run_id} -> outputs[].id) or run webhooks.

​
Video URL Requirements & Limits

The video_urls field supports two types of URLs: YouTube URLs:
  • Supports standard YouTube video URLs (e.g., https://www.youtube.com/watch?v=VIDEO_ID)
  • Maximum duration: 5 hours per video
  • The system automatically validates the video exists and checks duration before processing
Signed URLs (HTTP/HTTPS):
  • Must be HTTP or HTTPS URLs pointing to video files
  • Maximum file size: 5 GB per video
  • Maximum duration: 5 hours per video

​
Modifying Node Parameters

You can override specific parameters for any node in your agent workflow using the update_params field. This allows you to dynamically change behavior (like clip duration, prompt text, or number of clips) at runtime. To find the correct parameters:
  1. Open your agent in the Mosaic Dashboard
  2. Click the settings menu on the node you want to modify
  3. Scroll down to the API info dropdown
  4. Open the dropdown to find the Agent node ID
  5. Click Copy params to get the JSON structure
The copied JSON will look like this, where the key is the agent_node_id (UUID) and the value object contains the parameters you can override: 
{
  "bf750792-a2e9-48c2-9d39-24f892772f6a": {
    "num_clips": 10,
    "target_duration": 60
  }
}
Pass this entire object as the update_params value in your API request.

​
update_params validation behavior

Mosaic validates update_params before creating the run:
  • Unknown agent_node_id keys return 400
  • Invalid parameter types/values return 400
  • Protected/system nodes (for example Video Input/Destination/trigger nodes) cannot be overridden with update_params
If validation fails, the run is not created.

​
Bypassing Nodes at Runtime

Use ignore_nodes to skip one or more nodes for a single run without editing the saved agent template. For each ignored node:
  • Incoming connections to the node are rewired to its downstream nodes
  • The ignored node is removed from the runtime DAG for that run only
  • The template itself is unchanged
{
  "video_urls": ["https://youtube.com/watch?v=..."],
  "ignore_nodes": [
    "8cbfd03e-6e85-4f3d-b4b9-8de0b5bfb6a4"
  ],
  "update_params": {
    "35a12345-6789-abcd-ef01-234567890abc": {
      "audio_id": "your-uploaded-audio-uuid"
    }
  }
}

​
Uploading Media for Node Parameters

Some nodes accept images, audio, or videos as parameters. To set these programmatically, use the Uploads API to upload your files and get their UUIDs: 
{
  "video_urls": ["https://youtube.com/watch?v=..."],
  "update_params": {
    "35a12345-6789-abcd-ef01-234567890abc": {
      "audio_id": "your-uploaded-audio-uuid"
    },
    "76b23456-7890-efab-cd12-345678901bcd": {
      "image_id": "your-uploaded-image-uuid"
    }
  }
}
See the Upload Flow for the complete upload process.

​
Chaining Runs with node_render_ids

You can feed outputs from a previous run directly into another run by passing render IDs returned in webhooks or from GET /agent_run/[run_id] (outputs[].id). Single-input shorthand: 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "node_render_ids": [
      "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "8cbfd03e-6e85-4f3d-b4b9-8de0b5bfb6a4"
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'
Canonical video_inputs form: 
curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "video_inputs": [
      {
        "agent_node_id": "11111111-1111-1111-1111-111111111111",
        "node_render_ids": [
          "7ba7b810-9dad-11d1-80b4-00c04fd430c8"
        ]
      }
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
Mimir Integration

Mosaic can ingest video directly from Mimir using mimir_assets. This downloads the video from your Mimir instance, stores Mimir metadata (item ID, artifact type, connection details) as source_info on the video record, and makes it available for Premiere Pro linking in downstream tiles.

​
Prerequisites

  1. Go to Settings > Integrations in the Mosaic dashboard.
  2. Add your Mimir instance URL (e.g. https://mimir.mjoll.no) and an API key generated from your Mimir user settings.
  3. Mosaic verifies the connection on save. If verification fails, check that the URL and API key are correct.

​
Single Mimir asset

curl -X POST "https://api.mosaic.so/agent/[agent_id]/run" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mimir_assets": [
      {
        "id": "b60d57d2-4b12-a80c-6f14-c5eefaa91460",
        "artifact": "highres"
      }
    ],
    "callback_url": "https://your-webhook.com/callback"
  }'

​
Multiple Mimir assets with different artifacts

{
  "mimir_assets": [
    { "id": "b60d57d2-4b12-a80c-6f14-c5eefaa91460", "artifact": "highres" },
    { "id": "a1e0b6bd-d3be-4d1b-a529-41dd8927325e", "artifact": "proxy" }
  ],
  "callback_url": "https://your-webhook.com/callback"
}

​
Mimir assets in multi-input workflows

{
  "video_inputs": [
    {
      "agent_node_id": "11111111-1111-1111-1111-111111111111",
      "mimir_assets": [
        { "id": "b60d57d2-4b12-a80c-6f14-c5eefaa91460" }
      ]
    },
    {
      "agent_node_id": "22222222-2222-2222-2222-222222222222",
      "video_urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]
    }
  ],
  "callback_url": "https://your-webhook.com/callback"
}

​
mimir_assets entry schema

FieldTypeRequiredDescription
idstring (UUID)YesMimir item ID.
artifactstringNoWhich artifact variant to download (see table below). Defaults to highres.

​
Artifact options

ValueBehavior
highresDownloads the high-resolution source file. Default when artifact is omitted. Returns 400 if the item has no highres available.
proxyDownloads the lower-resolution proxy. Returns 400 if the item has no proxy available.
autoPrefers highres if available, falls back to proxy. Returns 400 only if neither is available.
Regardless of which artifact is downloaded, the Mimir item ID is always stored in source_info so Premiere Pro exports can link back to the original asset in Mimir.
mimir_assets require an organization-scoped API key (mk_ prefix). If no Mimir connection is configured for your organization, the API returns a 400 error explaining how to set one up.

​
How Mimir metadata flows

When a Mimir asset is ingested:
  1. Mosaic fetches the item details from your Mimir instance.
  2. The selected artifact URL (highres or proxy) is downloaded.
  3. Mimir metadata (item ID, artifact type, connection details) is stored in videos.source_info.
  4. Downstream tiles (e.g. News UK, Sun) that generate Premiere Pro projects use this metadata to link clips back to Mimir.

​
Agent graph best practices

  • For “shorter/tighter” edits, place Rough Cut and/or Clips before style-heavy nodes.
  • Place Reframe before Captions, Cinematic Captions, Motion Graphics, and Watermark so overlays are composed against final framing.
  • Keep update_params minimal and explicit (only send fields you want to override).

​
Publish to social after render

After run completion, retrieve outputs[].video_url from GET /agent_run/[run_id] and send that URL in media_urls to POST /social/post.

​
Response

{
  "run_id": "7f8d9c2b-4a6e-8b3f-1d5c-9e2f3a4b5c6d"
}
The run_id is used to track the progress of your agent run.