Agents

Update a tool

Update a tool by id. Pass rotate_secret: true to mint a new webhook signing secret, returned once as hmac_secret. Requires the omni:session scope.

post/v1/tools/{id}

Request

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

Path parameters

idstring required

Request body

namestring
descriptionstring
input_schemaobject
webhook_urlstring uri nullable
execution'server' | 'client'
auth_headerstring nullable
auth_secretstring nullable

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

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

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)

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
hmac_secretstring

Returned once at creation for webhook signature verification.

Example response

{
  "object": "tool"
}

Changes

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