Update Agent - Mosaic API Docs

Updates an existing agent. Graph mutation is action-based: send ordered operations (create_node, update_node, delete_node, create_connection, delete_connection). Node positions are always backend-managed (auto-layout).

Request

curl -X POST "https://api.mosaic.so/agent/123e4567-e89b-12d3-a456-789012345678/update" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "create_node",
        "temp_ref_id": "video_input_1",
        "node_type_id": "9451e6ff-ac7f-4317-9055-a2f35f641b29"
      },
      {
        "op": "create_node",
        "temp_ref_id": "captions_1",
        "node_type_id": "cdccb204-168e-4aec-aa72-480b11e74324",
        "params_used": {
          "caption_style": "colored"
        }
      },
      {
        "op": "create_connection",
        "source_temp_ref_id": "video_input_1",
        "target_temp_ref_id": "captions_1"
      }
    ]
  }'

You can also call the same operation with PATCH /agent/{agent_id}/update.

Body Parameters

Field	Type	Required	Description
`name`	string	No	Agent name (`1-120` chars).
`description`	string	No	Agent description (`<=5000` chars).
`visibility`	string	No	`public` or `private`.
`operations[]`	array	No	Ordered graph operations for node/connection mutations.

At least one of name, description, visibility, or operations is required.

Operation Types (Detailed)

`create_node`

Field	Type	Required	Description
`op`	string	Yes	Must be `"create_node"`.
`node_type_id`	string (UUID)	Yes	Node type to instantiate.
`temp_ref_id`	string	No	Request-scoped temporary reference for this newly created node. Use this in later operations in the same request. Not persisted.
`params_used`	object	No	Initial node parameters.

Backend behavior: creates a new node, assigns a persisted agent_node_id, and returns mapping details in created_nodes. You cannot supply agent_node_id in create_node; use returned IDs for later operations. temp_ref_id is only valid within the current update request. It is never saved and cannot be reused in future update calls.

`update_node`

Field	Type	Required	Description
`op`	string	Yes	Must be `"update_node"`.
`agent_node_id`	string (UUID)	Yes	Existing persisted node to update.
`params_used`	object	Yes	Parameter patch object merged into current node params.

`delete_node`

Field	Type	Required	Description
`op`	string	Yes	Must be `"delete_node"`.
`agent_node_id`	string (UUID)	Yes	Existing persisted node to delete.

Backend behavior: also removes connections where this node is source or target.

`create_connection`

Field	Type	Required	Description
`op`	string	Yes	Must be `"create_connection"`.
`source_agent_node_id`	string (UUID)	Conditional	Source existing node ID. Provide this or `source_temp_ref_id`.
`source_temp_ref_id`	string	Conditional	Source temp ref from earlier `create_node` operation in the same request. Provide this or `source_agent_node_id`.
`target_agent_node_id`	string (UUID)	Conditional	Target existing node ID. Provide this or `target_temp_ref_id`.
`target_temp_ref_id`	string	Conditional	Target temp ref from earlier `create_node` operation in the same request. Provide this or `target_agent_node_id`.

Rules:

Provide exactly one source reference (source_agent_node_id or source_temp_ref_id).
Provide exactly one target reference (target_agent_node_id or target_temp_ref_id).
source_temp_ref_id and target_temp_ref_id must reference a temp_ref_id created by an earlier create_node operation in the same request.

Mutation execution is atomic: if any operation fails validation or persistence, no graph changes are saved. Error messages include the operation step (for example, Operation 3: ...) to make retries deterministic.

`delete_connection`

Field	Type	Required	Description
`op`	string	Yes	Must be `"delete_connection"`.
`source_agent_node_id`	string (UUID)	Conditional	Source existing node ID. Provide this or `source_temp_ref_id`.
`source_temp_ref_id`	string	Conditional	Source temp ref from earlier `create_node` operation in the same request. Provide this or `source_agent_node_id`.
`target_agent_node_id`	string (UUID)	Conditional	Target existing node ID. Provide this or `target_temp_ref_id`.
`target_temp_ref_id`	string	Conditional	Target temp ref from earlier `create_node` operation in the same request. Provide this or `target_agent_node_id`.

To rewire a connection, send delete_connection then create_connection in the same operations array; execution order is preserved and applied atomically.

Response

{
  "success": true,
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "operations_applied": 3,
  "created_nodes": [
    {
      "temp_ref_id": "video_input_1",
      "agent_node_id": "11111111-1111-1111-1111-111111111111"
    },
    {
      "temp_ref_id": "captions_1",
      "agent_node_id": "22222222-2222-2222-2222-222222222222"
    }
  ]
}

Validation Error Response

When parameter validation fails, the API returns all detected issues in one response:

{
  "detail": "Invalid node parameters: Node 11111111-1111-1111-1111-111111111111: unknown parameter 'bad_key'; Node 22222222-2222-2222-2222-222222222222: Required parameter 'prompt' is missing",
  "issues": [
    {
      "code": "unknown_parameter",
      "message": "unknown parameter 'bad_key'",
      "node_id": "11111111-1111-1111-1111-111111111111",
      "node_type_id": "9451e6ff-ac7f-4317-9055-a2f35f641b29",
      "param_name": "bad_key",
      "operation_step": 1
    },
    {
      "code": "invalid_parameter",
      "message": "Required parameter 'prompt' is missing",
      "node_id": "22222222-2222-2222-2222-222222222222",
      "node_type_id": "cdccb204-168e-4aec-aa72-480b11e74324",
      "param_name": "prompt",
      "operation_step": 2
    }
  ]
}

​Request

​Body Parameters

​Operation Types (Detailed)

​create_node

​update_node

​delete_node

​create_connection

​delete_connection

​Response

​Validation Error Response