​
GET /get-user-agents-simple

Return a lightweight list of your own agents – handy for populating dropdowns or showing recent creations in a UI.

QueryTypeDefaultNotes
limitinteger (1-100)allCaps the number of agents returned (newest first)

Authentication is identical to other operational endpoints:

  • Bearer API key (mk_…) or X-API-Key header
  • Supabase session JWT for the Mosaic dashboard

​
Example – list the five most-recent agents

curl -s "https://api.usemosaic.ai/api/get-user-agents-simple?limit=5" \
     -H "Authorization: Bearer $MOSAIC_API_KEY"

​
Response

{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "My Caption Preset",
      "description": "Animated captions in brand colours",
      "created_at": "2025-06-01T12:00:00Z"
    }
  ]
}

The endpoint returns only your agents; there is no global marketplace yet. Results are sorted by created_at descending.

​
POST /run-agent

Execute an agent workflow on an uploaded video file.

Let Mosaic choose an agent based on your prompt:

curl -X POST "https://api.usemosaic.ai/api/run-agent" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "Generate a summary of the video"
  }'
FieldTypeRequiredDescription
file_idstring (UUID)✅ID of the uploaded file
agent_idstring (UUID)⚠️ID of the agent to run (mutually exclusive with prompt)
promptstring⚠️Natural-language instruction; Mosaic picks an agent & parameters (mutually exclusive with agent_id)
parametersobjectKey-value overrides for agent fields
autobooleanLet Mosaic choose optimal parameters (only used with agent_id)
Use either agent_id OR prompt, not both. When using prompt, Mosaic automatically selects the best agent and parameters.

​
Response

{
  "agent_run_id": "run_uuid",
  "project_id": "project_uuid",
  "agent_group_id": "group_uuid"
}

​
GET /get-agent-run/

Get full run details including the workflow graph.

​
Response

{
  "id": "run_uuid",
  "status": "running | completed | failed",
  "graph": {
    "nodes": [...],
    "edges": [...]
  }
}

​
GET /get-agent-run-simple/

Returns the same high-level metadata without the heavy graph payload. Poll this endpoint every ~5 seconds for updates on agent runs.

​
GET /get-agent-run-outputs/

Retrieve signed download URLs for all outputs of the run.

{
  "outputs": [
    {
      "node_id": "node_uuid",
      "file_id": "file_uuid",
      "download_url": "https://...",
      "thumbnail_url": "https://...",
      "duration_ms": 30000,
      "file_size": 1048576,
      "status": "success"
    }
  ]
}

​
POST /retry-agent-run-node/

Retry a specific failed node within an agent run instead of re-running the entire workflow.

FieldTypeRequiredDescription
agent_run_node_id (path)UUID✅ID of the node to retry. Must currently have status=failed.

Authentication: same as other operational endpoints – Bearer API key (mk_…) or Supabase session. Anonymous requests are rejected with 401.

​
Request

POST /retry-agent-run-node/{agent_run_node_id}
Authorization: Bearer mk_live_xxx…
Content-Type: application/json

{}

​
Successful response

{
  "success": true,
  "agent_run_node_id": "ab12cdef-3456-7890-abcd-ef1234567890",
  "status": "initiated",
  "message": "Agent run node retry initiated"
}

HTTP 200 — the node (and all downstream nodes) are reset to not_started; the parent run switches back to `