API ReferenceTools

Update

Updates a tool by name or ID.

Authentication

AuthorizationBearer
Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).

Path parameters

nameOrIdstringRequired
The name or the ID of the tool to update.

Query parameters

projectstringOptionalDefaults to main

The name of the project containing the tool. Only used when nameOrId is a name.

Request

This endpoint expects an object.
namestringOptionalformat: "^[a-z0-9_]+$"

The name of the tool. Must be snake_case and unique within the organization.

descriptionstringOptional
A description of what the tool does.
execution_modeenumOptional
Mode of operation.
contextstringOptional

The static context returned to the agent. Only applicable to custom_context tools.

parameterslist of objects or objectOptional

The tool’s parameters, either as a flat array of parameter definitions or as a raw JSON Schema object (use the object form for nested parameters). Replaces the tool’s existing parameters, including the form they are stored in. For custom_webhook tools: when sending an array, location is required for POST and defaults to "query_string" for GET, and parameter_locations must not be sent; when sending a JSON Schema object, placement is supplied in parameter_locations. For custom_websocket, built_in_transfer_to_phone_number, and built_in_transfer_to_agent tools: location must not be specified.

parameter_locationsmap from strings to enumsOptional

Where each top-level parameter is sent in the webhook request, as a map from parameter name to location. Only for custom_webhook tools whose parameters are a raw JSON Schema object. Can be sent on its own to move existing parameters without resending parameters; entries are merged over the tool’s current placement, so parameters left out keep where they were. Every key must name a top-level parameter. For POST webhooks, every parameter needs a placement. For GET webhooks, unplaced parameters default to "query_string" and "request_body" is not allowed.

endpoint_methodenumOptional

HTTP method for webhook tools. When switching from POST to GET, a tool with request body parameters must also send new parameters (or parameter_locations) placing them in the query string.

endpoint_urlstringOptionalformat: "uri"
URL for webhook tools. Must be a publicly routable HTTPS URL without embedded credentials.
endpoint_headersmap from strings to strings or nullOptional
Headers for webhook tools. Set to null to clear existing headers.
endpoint_timeout_msintegerOptional1000-180000
tool_call_output_timeout_msintegerOptional1000-180000
phone_numberstring or nullOptional
The E.164 formatted phone number to transfer calls to. Set to null if the agent should determine the phone number.
dtmfstring or nullOptional

DTMF digits to send after the transfer connects (e.g., “1234”). Can be set to null to remove DTMF. Ignored when dynamic_dtmf is true.

dynamic_dtmfbooleanOptional

When true, the agent determines the DTMF digits at call time (and may choose to send none); the static dtmf is ignored. Only sent when use_agent_phone_number is true (not on a SIP REFER transfer).

use_agent_phone_numberbooleanOptional

When true, Phonic will transfer the call using the agent’s phone number. When false, Phonic will transfer the call using the phone number of the party to whom the agent is connected. This is only available for built_in_transfer_to_phone_number tools.

detect_voicemailbooleanOptional

When true, Phonic will listen in and tell the user if the transfer hits voicemail. This is only available for built_in_transfer_to_phone_number tools when use_agent_phone_number is true.

agents_to_transfer_tolist of stringsOptional
Array of agent names that the LLM can choose from when transferring. All agents must exist in the same project as the tool.
require_speech_before_tool_callbooleanOptional
When true, forces the agent to speak before executing the tool.
speech_before_tool_callenumOptional

For built_in_natural_conversation_ending and built_in_keypad_input tools. Whether the agent must speak before calling the tool (“required”), the model decides (“optional”), or the agent must stay silent (“suppressed”). Not used by other tool types.

wait_for_speech_before_tool_callbooleanOptional

If true, the agent will wait to finish speaking before executing the tool. This is only available for custom_webhook and custom_websocket tools.

forbid_speech_after_tool_callbooleanOptional

When true, forbids the agent from speaking after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools.

forbid_tool_call_after_speechbooleanOptional

When true, forbids the agent from calling the tool right after it has spoken. Available for custom_webhook and custom_websocket tools.

allow_tool_chainingbooleanOptional

When true, allows the agent to chain and execute other tools after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools.

wait_for_responsebooleanOptional

The agent doesn’t typically wait for the response of async custom_websocket tools. When true, makes the agent wait for a response, not call other tools and inform the user of the result. Only available for async custom_websocket tools.

Response

Success response
successboolean
Whether the tool was updated successfully.

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error