Assign Tool to Workflow

POST /client-tools/:id/assign Assign a catalog tool to an agent. Inserts an inherited workflow tool that mirrors the catalog tool’s content fields and stays in sync with it on future Update Client Tool edits. Idempotent: re-assigning an already-assigned tool returns the existing assignment (still 200, no duplicate row). Both the client tool and the target agent must belong to your account.

Path Parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	Client tool ID

Request Body

Field	Type	Required	Description
`workflow_id`	string (uuid)	Yes	Agent to assign the tool to

Responses

`200` — Assigned (created or already existed)

{
  "success": true,
  "workflow_tool": {
    "id": "9a1b2c3d-0000-4000-8000-000000000001",
    "name": "check_subscription",
    "description": "Checks whether the lead has an active subscription",
    "url": "https://api.acme.com/subscriptions/status",
    "method": "GET",
    "timeout_ms": 10000,
    "parameters": { "type": "object", "properties": {} },
    "headers": {},
    "query_parameters": {},
    "is_active": true,
    "sort_order": 0,
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "source_tool_id": "7c1b2c3d-0000-4000-8000-000000000002",
    "inherited": true,
    "auto_run_on_entry": false,
    "call_once": false,
    "available_in_statuses": null
  }
}

Response Fields — WorkflowTool (public shape)

Field	Type	Description
`id`	string (uuid)	Workflow tool identifier
`name`	string	snake_case name, copied from the catalog tool
`description`	string	Copied from the catalog tool, kept in sync on catalog edits
`url`	string	Copied from the catalog tool, kept in sync on catalog edits
`method`	string	Copied from the catalog tool, kept in sync on catalog edits
`timeout_ms`	integer	Copied from the catalog tool, kept in sync on catalog edits
`parameters`	object	Copied from the catalog tool, kept in sync on catalog edits
`headers`	object	Copied from the catalog tool, kept in sync on catalog edits
`query_parameters`	object	Copied from the catalog tool, kept in sync on catalog edits
`is_active`	boolean	Copied at assign time, then kept in sync on catalog edits
`sort_order`	integer	Set fresh at assign time from the catalog tool’s `sort_order`. Not synced afterwards
`workflow_id`	string (uuid)	Agent this assignment belongs to
`source_tool_id`	string (uuid)	The catalog tool this row was assigned from
`inherited`	boolean	`true` for a catalog assignment (vs. a standalone Create Workflow Tool)
`auto_run_on_entry`	boolean	Run automatically when a lead enters an eligible status
`call_once`	boolean	Allow only one call per lead
`available_in_statuses`	string[] \| null	Funnel status keys where this tool is offered. `null` means every status

This same field shape is returned by Create Workflow Tool.

`400` — Validation error

{
  "error": "Invalid input",
  "message": "workflow_id is required"
}

Also returned as "tool id must be a valid UUID" or "workflow_id must be a valid UUID".

`401` — Authentication error

See Authentication.

`404` — Not found

{
  "error": "Not found",
  "message": "Client tool not found"
}

Also returned as "Workflow not found" when the agent doesn’t belong to your account.

`409` — Conflict

{
  "error": "Conflict",
  "message": "A tool named \"check_subscription\" already exists in this workflow"
}

Returned when a different tool (not this catalog tool) already occupies that name in the target agent.

​Path Parameters

​Request Body

​Responses

​200 — Assigned (created or already existed)

​Response Fields — WorkflowTool (public shape)

​400 — Validation error

​401 — Authentication error

​404 — Not found

​409 — Conflict

​500 — Internal server error