Skip to main content
POST
/
tools
Create Tool
curl --request POST \
  --url https://api.kejue.co/api/v1/tools \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>",
  "http_config": {
    "url": "<string>",
    "method": "POST",
    "headers": {},
    "auth_config": {},
    "timeout_ms": 30000
  },
  "display_name": "<string>",
  "description": "<string>",
  "dynamic_parameters": [
    {
      "name": "<string>",
      "description": "",
      "param_type": "string",
      "location": "body",
      "required": false,
      "source": "ai"
    }
  ],
  "static_parameters": [
    {
      "name": "<string>",
      "value": "<string>",
      "location": "body"
    }
  ],
  "response_schema": {},
  "timeout": 30000,
  "retry_count": 0,
  "precomputable": false,
  "agent_reaction": "speaks"
}
'
{
  "id": "<string>",
  "name": "<string>",
  "tool_type": "<string>",
  "timeout": 123,
  "retry_count": 123,
  "display_name": "<string>",
  "description": "<string>",
  "http_config": {},
  "parameters": {},
  "response_schema": {},
  "precomputable": false,
  "agent_reaction": "speaks",
  "created_at": "<string>",
  "updated_at": "<string>"
}

Authorizations

X-API-Key
string
header
required

Workspace API key (e.g. kej_live_...)

Body

application/json

Create a custom HTTP tool.

name
string
required

Tool name (unique per workspace)

Required string length: 1 - 100
http_config
HttpConfigInput · object
required

HTTP configuration

display_name
string | null

Display name

description
string | null

Description of when the tool should be used

dynamic_parameters
DynamicParameterInput · object[] | null

Parameters provided by the AI agent at runtime with location routing

static_parameters
StaticParameterInput · object[] | null

Fixed parameters always sent with requests

response_schema
Response Schema · object

Expected response format

timeout
integer
default:30000

Tool timeout in milliseconds

Required range: 1000 <= x <= 60000
retry_count
integer
default:0

Number of retries on failure

Required range: 0 <= x <= 5
precomputable
boolean
default:false

Voice only: if true, Ultravox may invoke this tool speculatively. Safe only for non-mutating tools. Ignored for chat.

agent_reaction
enum<string>
default:speaks

Voice only: how the agent reacts when this tool fires. Ignored for chat.

Available options:
speaks,
silent,
speaks-once

Response

Successful Response

A custom HTTP tool (public-safe response).

id
string
required
name
string
required
tool_type
string
required
timeout
integer
required
retry_count
integer
required
display_name
string | null
description
string | null
http_config
Http Config · object
parameters
Parameters · object
response_schema
Response Schema · object
precomputable
boolean
default:false
agent_reaction
enum<string>
default:speaks

How the voice agent reacts when a tool call fires.

Ultravox-specific. Ignored by chat tool-calling.

  • SPEAKS: agent speaks naturally around the tool call (Ultravox default)
  • SILENT: agent stays silent until the tool returns
  • SPEAKS_ONCE: agent speaks at most one filler line during the tool call
Available options:
speaks,
silent,
speaks-once
created_at
string | null
updated_at
string | null