API Tools
An API tool describes an external HTTP request that AI assistants can make: the endpoint, method, headers, and the parameters the AI fills in or that are always fixed. Create a tool once, then attach it to assistants through their api_tools field.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api-tools | List API tools |
GET | /api-tools/:id | Get an API tool |
POST | /api-tools | Create an API tool |
PATCH | /api-tools/:id | Update an API tool |
DELETE | /api-tools/:id | Delete an API tool |
Reads are limited to your API key's organization.
The API tool object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. Use it as api_tool_id on assistants. |
organization_id | integer | Required on create. Your API key's organization. |
name | string | Required. Tool name shown to the AI. |
description | string | What the tool does; the AI reads it to decide when to call the tool. |
endpoint | string | Required. Full URL. Path placeholders such as {order_id}, :order_id or {{order_id}} are replaced with parameter values. |
method | string | Required. GET or POST. |
parameters_schema | object | Required. JSON Schema (type: "object", properties, required) of the arguments the AI provides. |
url_parameters | array | null | Path and query parameters (see below). |
body_parameters | array | null | JSON body parameters for POST tools (see below). |
headers | object | null | Headers sent with every request, e.g. credentials for the external API. They are returned as stored, so treat responses as sensitive. |
response_example | object | null | Example response, for reference. |
created_at | string (date-time) | Read-only. Creation timestamp. |
updated_at | string (date-time) | Read-only. Last update timestamp. |
deleted_at | string (date-time) | null | Read-only. Set when the tool is deleted. |
Parameter object
Items of url_parameters and body_parameters:
| Field | Type | Description |
|---|---|---|
id | string | Your own unique ID for the parameter. |
name | string | Name sent to the external API (query key, path placeholder or body key). |
type | string | string, number, integer, boolean, array or object. |
description | string | Tells the AI what value to provide. |
required | boolean | The request fails if the value is missing. |
value_source | string | ai (default): the AI provides the value. fixed: fixed_value is always sent. |
fixed_value | any | Value sent when value_source is fixed. |
location | string | URL parameters only: path (replaces a placeholder in endpoint) or query. |
Attach a tool to an assistant
The assistant's api_tools array replaces the previous one, so include every tool the assistant should keep.
Related
Report an issue with this documentation
Please log in to report issues with our documentation.