Skip to main content
POST
/
agent
/
create
Create Agent
curl --request POST \
  --url https://api.example.com/agent/create
Creates a new agent and optionally saves its graph (nodes + connections) in the same request. If graph is omitted, Mosaic creates a starter graph with one Video Input node unless you set create_video_input_node=false.

​
Request

curl -X POST "https://api.mosaic.so/agent/create" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UGC Variants",
    "description": "Generate and caption UGC clips",
    "visibility": "private",
    "graph": {
      "nodes": [
        {
          "id": "video_input",
          "node_id": "9451e6ff-ac7f-4317-9055-a2f35f641b29",
          "position_x": 120,
          "position_y": 180,
          "params_used": {}
        },
        {
          "id": "captions",
          "node_id": "cdccb204-168e-4aec-aa72-480b11e74324",
          "position_x": 520,
          "position_y": 180,
          "params_used": {
            "caption_style": "colored",
            "caption_font": "Montserrat"
          }
        }
      ],
      "connections": [
        {
          "source_agent_node_id": "video_input",
          "target_agent_node_id": "captions"
        }
      ]
    }
  }'

​
Body Parameters

FieldTypeRequiredDescription
namestringNoAgent name (1-120 chars).
descriptionstringNoAgent description (<=5000 chars).
visibilitystringNopublic or private.
workspace_idstringNoTarget workspace UUID. Defaults to organization primary workspace.
create_video_input_nodebooleanNoWhen graph is omitted, auto-create starter Video Input node (true by default).
graph.nodes[]arrayNoGraph nodes to save.
graph.connections[]arrayNoDirected graph edges to save.

​
Validation Behavior

  • Node params are validated against tile metadata and backend node schemas.
  • Unknown params are rejected when a schema is available.
  • Graphs must be acyclic (DAG).
  • Connection direction rules are enforced (e.g. trigger/content-generation source constraints).

​
Response

{
  "agent_id": "a7ac4cc6-2302-4b14-8fd1-a3287bfc7606",
  "name": "UGC Variants",
  "description": "Generate and caption UGC clips",
  "visibility": "private",
  "workspace_id": "31d7da52-e2ea-4d7d-9066-aa34df5890d0",
  "created_at": "2026-03-11T17:21:56.419Z",
  "updated_at": "2026-03-11T17:21:56.590Z",
  "graph_updated": true,
  "nodes_created": 2,
  "nodes_updated": 0,
  "nodes_deleted": 0,
  "connections_created": 1,
  "warnings": []
}