Skip to main content
POST
/
agent
/
{agent_id}
/
update
Update Agent
curl --request POST \
  --url https://api.example.com/agent/{agent_id}/update
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

FieldTypeRequiredDescription
namestringNoAgent name (1-120 chars).
descriptionstringNoAgent description (<=5000 chars).
visibilitystringNopublic or private.
operations[]arrayNoOrdered graph operations for node/connection mutations.
At least one of name, description, visibility, or operations is required.

​
Operation Types (Detailed)

​
create_node

FieldTypeRequiredDescription
opstringYesMust be "create_node".
node_type_idstring (UUID)YesNode type to instantiate.
temp_ref_idstringNoRequest-scoped temporary reference for this newly created node. Use this in later operations in the same request. Not persisted.
params_usedobjectNoInitial 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

FieldTypeRequiredDescription
opstringYesMust be "update_node".
agent_node_idstring (UUID)YesExisting persisted node to update.
params_usedobjectYesParameter patch object merged into current node params.

​
delete_node

FieldTypeRequiredDescription
opstringYesMust be "delete_node".
agent_node_idstring (UUID)YesExisting persisted node to delete.
Backend behavior: also removes connections where this node is source or target.

​
create_connection

FieldTypeRequiredDescription
opstringYesMust be "create_connection".
source_agent_node_idstring (UUID)ConditionalSource existing node ID. Provide this or source_temp_ref_id.
source_temp_ref_idstringConditionalSource temp ref from earlier create_node operation in the same request. Provide this or source_agent_node_id.
target_agent_node_idstring (UUID)ConditionalTarget existing node ID. Provide this or target_temp_ref_id.
target_temp_ref_idstringConditionalTarget 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

FieldTypeRequiredDescription
opstringYesMust be "delete_connection".
source_agent_node_idstring (UUID)ConditionalSource existing node ID. Provide this or source_temp_ref_id.
source_temp_ref_idstringConditionalSource temp ref from earlier create_node operation in the same request. Provide this or source_agent_node_id.
target_agent_node_idstring (UUID)ConditionalTarget existing node ID. Provide this or target_temp_ref_id.
target_temp_ref_idstringConditionalTarget 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
    }
  ]
}