API Tools API

Create reusable external HTTP tools that AI assistants can call.

Overview

API tools describe an external HTTP request, the values the AI must provide, and any fixed values that should always be sent. After a tool is created, associate it with an assistant by updating the assistant's api_tools array.

Base Endpoint: /api-tools

API Tool Object

json

Parameter Object

Use url_parameters for path and query values and body_parameters for JSON body values.

Field	Type	Description
`id`	String	Client-generated unique ID for the parameter
`name`	String	Parameter name sent to the external API
`type`	String	`string`, `number`, `integer`, `boolean`, `array`, or `object`
`description`	String	Explanation the AI uses to collect or infer the value
`required`	Boolean	Whether the value is required
`enum`	String[]	Optional allowed values
`value_source`	String	`ai` for AI-provided values or `fixed` for values you provide
`fixed_value`	Any	Value sent when `value_source` is `fixed`
`location`	String	For URL parameters, `query` or `path`
`properties`	Parameter[]	Nested fields for object parameters
`items`	Object	Item schema for array parameters

Fixed Values vs AI Values

Use value_source: "ai" when the assistant should provide the value from the conversation.
Use value_source: "fixed" when the same value should always be sent and the assistant should not decide it.

API Tools API

Overview

API Tool Object

Parameter Object

Fixed Values vs AI Values

Associate a Tool with an Assistant

Available Operations

Report an issue with this documentation