Skip to main content
POST
Create a tool revision

Authorizations

x-api-key
string
header
required

Path Parameters

tool_id
string<uuid>
required

Body

application/json
name
string
required
description
string | null
based_on_revision_id
string<uuid> | null
configuration
APICallConfiguration · object | null

Configuration for an API_CALL tool, stored in Tool.configuration.

Supports {{variable}} placeholders in url, headers, and body that are resolved at execution time from the tool's input variables and runtime metadata (via {{metadata.key}}).

transfer_target
TransferTargetInput · object | null

Operator-supplied config for a call_transfer target (ENG, voice).

A transfer target carries either a static destination (E.164 or sip: URI) or a dynamic destination_source (api_tool reference that resolves the destination at transfer time). The two are mutually exclusive. mode is always "cold".

destination validity (E.164 or sip: URI) is enforced at the service layer via :func:~src.custom_tools.api._shared.transfer_target.validate_transfer_target_config so a bad destination surfaces as a clean 422. The label / when-to-use are carried on the Tool's name / description, not here.

response_schema
ResponseFieldSelector · object | null

The projection applied to a tool response.

input_defaults
Input Defaults · object | null

Response

Successful Response

id
string<uuid>
required
tool_id
string<uuid>
required
name
string
required
description
string | null
required
status
string
required
created_by
string | null
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
default_count
integer
required
read-only

How many input variables carry an operator default (ENG-590).

pinned_count
integer
required
read-only

How many input variables are operator-pinned (ENG-590).

stale_input_fields
string[]
required
read-only

Configured variables removed/renamed/retyped by an operator edit.

merged_input_preview
Merged Input Preview · object
required
read-only

The input schema with each operator value injected as default.

configuration
APICallConfiguration · object | null

Configuration for an API_CALL tool, stored in Tool.configuration.

Supports {{variable}} placeholders in url, headers, and body that are resolved at execution time from the tool's input variables and runtime metadata (via {{metadata.key}}).

transfer_target
TransferTargetView · object | null

A call_transfer revision's stored target, surfaced on reads.

ToolRevisionResponse.configuration is api_call-typed and parses to None for a transfer config (it has no url), so this field carries the destination/mode back for the transfer-target picker. label / when_to_use come from the parent Tool's name / description.

Either destination (static) or destination_source (api_tool dynamic) is present, never both. The unused variant is omitted from serialization.

response_schema
ResponseFieldSelector · object | null

The projection applied to a tool response.

has_secrets
boolean
default:false
input_defaults
Input Defaults · object | null
compatibility
ToolCompatibilityReportResponse · object | null

Impact report shared by preflight analysis and successful promotion.

Pre-prod: findings are advisory warnings — promotion always succeeds. The has_blocking / active_blocking_* fields retain their literal blocking semantics (and therefore remain false/zero today).