Skip to main content
POST
Update a tool

Authorizations

Authorization
string
header
required

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

Path Parameters

id
string
required

Body

application/json
name
string
description
string
input_schema
object
config_schema
object

Declares the settings a tool needs. Render these as a form in your agent builder; capture answers on the agent's tool binding config.

webhook_url
string<uri> | null
execution
enum<string>
Available options:
server,
client
auth_header
string | null
auth_secret
string | null

Replace the stored webhook auth value, or null to clear it.

side_effect
enum<string>
Available options:
read,
action
timeout_ms
integer
Required range: 100 <= x <= 15000
status
enum<string>
Available options:
active,
disabled
rotate_secret
boolean

When true, mint a NEW webhook signing secret and return it once as hmac_secret. Zero-drop rotation: deploy verification that accepts both the old and new secret, call this, then drop the old one.

Response

Updated tool (includes hmac_secret only when rotate_secret was set)

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
hmac_secret
string

Returned once at creation for webhook signature verification.