workflows

Attach Tool To Node

Attach a CONFIGURED tool instance to a workflow node.

Workflow nodes never reference tool types (registry keys) directly — they only reference instances that already exist in agent_tools. The rule: a user cannot attach cold_transfer to a node; they must first create a configured instance like transfer_to_billing (with its sip_trunk_id, target_number, etc.) on an agent, then attach that instance_name here.

Validation:

If ?agent_id= is provided, the (agent_id, instance_name) pair MUST exist in agent_tools (active + enabled). Strict.
Otherwise, the instance_name MUST exist on at least one agent currently using this workflow (i.e. agents.workflow_id == this).
If the workflow is not yet attached to any agent, the request is rejected with 422 — bind the workflow to an agent first, then attach instances. (Avoids accumulating dangling string refs that only fail at runtime.)

POST

workflows

{workflow_id}

nodes

{node_id}

tools

Attach Tool To Node

curl --request POST \
  --url https://api.example.com/workflows/{workflow_id}/nodes/{node_id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_name": "<string>",
  "parameters": {}
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workflow_id

string<uuid>

required

node_id

string

required

Query Parameters

agent_id

string<uuid> | null

Body

application/json

Body for POST /workflows/{wf}/nodes/{node}/tools.

instance_name

string

required

Required string length: 1 - 120

parameters

Parameters · object

Response

Successful Response

Detach Tool From NodeDetach a tool instance from a workflow node.

Attach Tool To Node

curl --request POST \
  --url https://api.example.com/workflows/{workflow_id}/nodes/{node_id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_name": "<string>",
  "parameters": {}
}
'

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Documentation Index

Authorizations

Path Parameters

Query Parameters

Body

Response