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

MethodPathDescription
GET/api-toolsList API tools
GET/api-tools/:idGet an API tool
POST/api-toolsCreate an API tool
PATCH/api-tools/:idUpdate an API tool
DELETE/api-tools/:idDelete an API tool

Reads are limited to your API key's organization.

The API tool object

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID. Use it as api_tool_id on assistants.
organization_idintegerRequired on create. Your API key's organization.
namestringRequired. Tool name shown to the AI.
descriptionstringWhat the tool does; the AI reads it to decide when to call the tool.
endpointstringRequired. Full URL. Path placeholders such as {order_id}, :order_id or {{order_id}} are replaced with parameter values.
methodstringRequired. GET or POST.
parameters_schemaobjectRequired. JSON Schema (type: "object", properties, required) of the arguments the AI provides.
url_parametersarray | nullPath and query parameters (see below).
body_parametersarray | nullJSON body parameters for POST tools (see below).
headersobject | nullHeaders sent with every request, e.g. credentials for the external API. They are returned as stored, so treat responses as sensitive.
response_exampleobject | nullExample response, for reference.
created_atstring (date-time)Read-only. Creation timestamp.
updated_atstring (date-time)Read-only. Last update timestamp.
deleted_atstring (date-time) | nullRead-only. Set when the tool is deleted.

Parameter object

Items of url_parameters and body_parameters:

FieldTypeDescription
idstringYour own unique ID for the parameter.
namestringName sent to the external API (query key, path placeholder or body key).
typestringstring, number, integer, boolean, array or object.
descriptionstringTells the AI what value to provide.
requiredbooleanThe request fails if the value is missing.
value_sourcestringai (default): the AI provides the value. fixed: fixed_value is always sent.
fixed_valueanyValue sent when value_source is fixed.
locationstringURL 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.