Skip to main content
POST
/
v1
/
tools
Create or update a custom tool
curl --request POST \
  --url https://api.pyai.com/v1/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "auth_header": "<string>",
  "auth_secret": "<string>",
  "timeout_ms": 5000
}
'
{
  "object": "tool",
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "auth_header": "<string>",
  "has_auth": true,
  "timeout_ms": 123,
  "created_at": 123
}

Authorizations

​
Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Body

application/json
​
name
string
required
​
description
string
​
input_schema
object
​
config_schema
object

Optional. Declare customer settings this tool needs (captured per agent on the binding config).

​
webhook_url
string<uri>

HTTPS endpoint for the tool. Validated against an SSRF allow-list at registration (public HTTPS only; private/loopback/metadata rejected).

​
execution
enum<string>

How the tool runs. server = the Platform tool-executor calls webhook_url directly (default for endpoint tools; works on telephony). client = your connected app executes it (legacy client-loop). Defaults to server when webhook_url is set.

Available options:
server,
client
​
auth_header
string

Header name the executor injects the webhook auth value into (e.g. Authorization). Pair with auth_secret.

​
auth_secret
string

Auth value for your webhook (e.g. 'Bearer ...'). Stored encrypted at rest, injected by the executor, never echoed back.

​
side_effect
enum<string>
Available options:
read,
action
​
timeout_ms
integer
default:5000

Per-call budget (ms). Note the executor also enforces a platform hard ceiling (5000 ms by default); the effective budget is min(timeout_ms, ceiling). On timeout the model receives a synthetic soft { "error": "tool timed out" } and the turn continues.

Required range: 100 <= x <= 15000

Response

Updated existing tool (idempotent upsert by name)

​
object
string
Example:

"tool"

​
id
string
​
org_id
string | null
​
name
string
​
kind
enum<string>
Available options:
prebuilt,
custom
​
description
string
​
input_schema
object
​
config_schema
object

Customer settings this tool needs to run. Render as a form in your builder; save answers on the agent binding config.

​
webhook_url
string | null
​
execution
enum<string>

How the tool runs. hosted = PyAI runs it (prebuilt read catalog). server = the tool-executor calls your webhook. engine = the Omni call engine runs it natively (call control: transfer_to_human, send_dtmf, play_hold, collect, end_call) — not routed to the executor. client = your connected app.

Available options:
hosted,
server,
engine,
client
​
auth_header
string | null
​
has_auth
boolean

Whether a webhook auth secret is configured (the secret itself is never returned).

​
side_effect
enum<string>
Available options:
read,
action
​
timeout_ms
integer
​
status
enum<string>
Available options:
active,
disabled
​
created_at
integer