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
}
'

import requests

url = "https://api.pyai.com/v1/tools"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.pyai.com/v1/tools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pyai.com/v1/tools",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pyai.com/v1/tools"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/tools")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/tools")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}"

response = http.request(request)
puts response.read_body

{
  "object": "tool",
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "kind": "prebuilt",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "type": "string",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "execution": "hosted",
  "auth_header": "<string>",
  "has_auth": true,
  "side_effect": "read",
  "timeout_ms": 123,
  "status": "active",
  "created_at": 123
}

{
  "object": "tool",
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "kind": "prebuilt",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "type": "string",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "execution": "hosted",
  "auth_header": "<string>",
  "has_auth": true,
  "side_effect": "read",
  "timeout_ms": 123,
  "status": "active",
  "created_at": 123,
  "hmac_secret": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "invalid_request_error",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "invalid_request_error",
    "param": "<string>"
  }
}

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

tools

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
}
'

import requests

url = "https://api.pyai.com/v1/tools"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.pyai.com/v1/tools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pyai.com/v1/tools",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pyai.com/v1/tools"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pyai.com/v1/tools")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/tools")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"input_schema\": {},\n  \"config_schema\": {\n    \"fields\": [\n      {\n        \"key\": \"<string>\",\n        \"label\": \"<string>\",\n        \"required\": false,\n        \"secret\": false,\n        \"help\": \"<string>\",\n        \"placeholder\": \"<string>\",\n        \"options\": [\n          \"<string>\"\n        ]\n      }\n    ]\n  },\n  \"webhook_url\": \"<string>\",\n  \"auth_header\": \"<string>\",\n  \"auth_secret\": \"<string>\",\n  \"timeout_ms\": 5000\n}"

response = http.request(request)
puts response.read_body

{
  "object": "tool",
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "kind": "prebuilt",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "type": "string",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "execution": "hosted",
  "auth_header": "<string>",
  "has_auth": true,
  "side_effect": "read",
  "timeout_ms": 123,
  "status": "active",
  "created_at": 123
}

{
  "object": "tool",
  "id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "kind": "prebuilt",
  "description": "<string>",
  "input_schema": {},
  "config_schema": {
    "fields": [
      {
        "key": "<string>",
        "label": "<string>",
        "type": "string",
        "required": false,
        "secret": false,
        "help": "<string>",
        "placeholder": "<string>",
        "options": [
          "<string>"
        ]
      }
    ]
  },
  "webhook_url": "<string>",
  "execution": "hosted",
  "auth_header": "<string>",
  "has_auth": true,
  "side_effect": "read",
  "timeout_ms": 123,
  "status": "active",
  "created_at": 123,
  "hmac_secret": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "invalid_request_error",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "invalid_request_error",
    "param": "<string>"
  }
}

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).

Show child attributes

webhook_url

string<uri>

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

execution

enum<string>

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.

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

Callbacks

POST

{$request.body#/webhook_url}toolInvocation

Body

application/json

Signed server-tool delivery. Verify X-PyAI-Signature over the raw body and enforce timestamp freshness. Operation identity is deduplication metadata, not caller consent or conversation identity.

call_id

string

required

Tool invocation ID; may change across provider retries.

tool

string

required

org_id

string

required

agent_id

string | null

required

arguments

any

required

operation_id

string

Optional engine operation key stable across provider retries. Scope durable deduplication to the verified tenant and tool, reject changed arguments, and reconcile uncertain results before retrying. Legacy deliveries may omit it.

Pattern: ^[a-f0-9]{64}$

Response

200

Tool result; successful HTTP transport alone does not establish a completed action.

Response

Updated existing tool (idempotent upsert by name)

object

string

Example:

"tool"

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.

Show child attributes

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

Omni

MCP

Cast

Integrations

Dub

Console creations

Identity

Call Integrations

Sandbox

Startup Program

Models

Speech To Text (Hear)

Text To Speech (Speak)

Agents

Clone

Transcription Jobs

Trace

Recap

AMD

Knowledge Bases

Telephony

WhatsApp

Create or update a custom tool

Authorizations

Body

Callbacks

Body

Response

Response