Agents

Create or update a custom tool

Register a custom tool. Idempotent upsert on (org, name): if your org already has a tool with this name, it is updated in place (HTTP 200, no duplicate, hmac_secret preserved), so re-syncing the same tool from a multi-tenant deploy is safe; otherwise a new tool is created (HTTP 201, hmac_secret returned once). A prebuilt/global tool of the same name never blocks creating your org's tool. In server mode PyAI calls your webhook_url (signed, network-isolated), works on phone calls; client mode runs on the WebSocket. Requires the omni:session scope.

post/v1/tools

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/tools
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

namestring required
descriptionstring
input_schemaobject
webhook_urlstring uri

HTTPS URL PyAI calls when this server tool runs. Public HTTPS only; private, loopback, and metadata addresses are rejected at registration.

execution'server' | 'client'

How the tool runs. server = PyAI calls webhook_url (default when webhook_url is set; works on phone calls). client = your connected app executes it over the Omni socket. Register server tools here; do not put webhook_url on the Omni configure frame.

auth_headerstring

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

auth_secretstring

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

side_effect'read' | 'action'
timeout_msinteger

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.

Response

Updated existing tool (idempotent upsert by name)

objectstring
idstring
org_idstring nullable
namestring
kind'prebuilt' | 'custom'
descriptionstring
input_schemaobject
webhook_urlstring nullable
execution'hosted' | 'server' | 'engine' | 'client'

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.

auth_headerstring nullable
has_authboolean

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

side_effect'read' | 'action'
timeout_msinteger
status'active' | 'disabled'
created_atinteger

Example response

{
  "object": "tool"
}

Changes

No recorded changes to this operation across all 1 revision of this API.