Skip to main content
POST /workflows/:id/tools Add a custom HTTP tool the agent can call — your own endpoint, described the way an LLM function call is described. Gate it to specific funnel stages with Set Stage Gate.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (uuid)YesAgent ID

​
Request Body

FieldTypeRequiredDescription
namestringYessnake_case, matching ^[a-z][a-z0-9_]*$. Immutable after creation
descriptionstringYesWhat the tool does and when the agent should call it
urlstringYesEndpoint the tool calls
methodstringNoGET, POST, PUT, PATCH, or DELETE. Default POST
parametersobjectNoJSON-schema-style object describing the tool’s call arguments. Default { "type": "object", "properties": {} }
headersobjectNoStatic headers sent with every call, e.g. { "Authorization": "Bearer ..." }
query_parametersobjectNoStatic query string params sent with every call
timeout_msintegerNoClamped to 1,000 to 120,000. Default 10000
available_in_statusesstring[]NoFunnel status keys where this tool is offered. Omit or null for every status
auto_run_on_entrybooleanNoRun automatically when a lead enters an eligible status. Default false
call_oncebooleanNoAllow only one call per lead. Default false
is_activebooleanNoDefault true

​
Responses

​
201 — Tool created

{
  "success": true,
  "tool": {
    "id": "9a1b2c3d-0000-4000-8000-000000000001",
    "name": "check_availability",
    "description": "Checks open slots on the sales calendar for a given day",
    "method": "GET",
    "url": "https://api.acme.com/availability",
    "is_active": true,
    "available_in_statuses": null,
    "auto_run_on_entry": false,
    "call_once": false,
    "sort_order": 0
  }
}

​
400 — Validation error

{
  "error": "Invalid input",
  "message": "name must be snake_case (^[a-z][a-z0-9_]*$)"
}
Also returned as "description is required", "url is required", or "method must be one of: GET, POST, PUT, PATCH, DELETE".

​
401 — Authentication error

See Authentication.

​
404 — Not found

{
  "error": "Not found",
  "message": "Workflow not found"
}

​
409 — Conflict

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

​
500 — Internal server error

Last modified on July 10, 2026