Create tool

Create a new tool for an assistant. The tool type must be available for the assistant's provider configuration.

Request

POST https://superinterface.ai/api/cloud/assistants/{assistantId}/tools

Authentication

Include your private API key in the request headers:

Authorization: Bearer YOUR_PRIVATE_API_KEY

Path Parameters

Parameter	Type	Description
`assistantId`	string	The ID of the assistant

Request Body

Parameter	Type	Required	Description
`type`	string	Yes	`WEB_SEARCH`, `FILE_SEARCH`, `CODE_INTERPRETER`, `IMAGE_GENERATION`, or `COMPUTER_USE`
`fileSearchTool`	object	No	Settings for file search tools
`imageGenerationTool`	object	No	Settings for image generation tools
`computerUseTool`	object	No	Settings for computer use tools

WEB_SEARCH and CODE_INTERPRETER have no configurable settings — only the type field is needed.

`fileSearchTool` fields

Field	Type	Required	Default	Description
`vectorStoreIds`	string[]	No	`[]`	IDs of vector stores to search
`maxNumResults`	number	No	`20`	Maximum number of results to return

`imageGenerationTool` fields

Field	Type	Required	Default	Description
`model`	string	No	`gpt-image-1`	Model to use (`gpt-image-1`)
`quality`	string	No	`AUTO`	`AUTO`, `LOW`, `MEDIUM`, or `HIGH`
`size`	string	No	`AUTO`	`AUTO`, `SIZE_1024_1024`, `SIZE_1024_1536`, or `SIZE_1536_1024`
`outputFormat`	string	No	`PNG`	`PNG`, `WEBP`, or `JPEG`
`background`	string	No	`AUTO`	`AUTO`, `TRANSPARENT`, or `OPAQUE`
`partialImages`	number	No	`0`	Number of partial images to stream

`computerUseTool` fields

Field	Type	Required	Default	Description
`displayWidth`	number	Yes	—	Display width in pixels (640–4096)
`displayHeight`	number	Yes	—	Display height in pixels (480–4096)
`environment`	string	No	`LINUX`	`LINUX`, `WINDOWS`, `MACOS`, or `BROWSER`
`mcpServerId`	string?	No	`null`	ID of an MCP server linked to this assistant

Example request — web search

Example request — code interpreter

Example request — file search

curl -X POST "https://superinterface.ai/api/cloud/assistants/{assistantId}/tools" \ -H "Authorization: Bearer YOUR_PRIVATE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "FILE_SEARCH", "fileSearchTool": { "vectorStoreIds": ["vs_abc123"], "maxNumResults": 10 } }'

Example request — image generation

curl -X POST "https://superinterface.ai/api/cloud/assistants/{assistantId}/tools" \ -H "Authorization: Bearer YOUR_PRIVATE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "IMAGE_GENERATION", "imageGenerationTool": { "model": "gpt-image-1", "quality": "HIGH", "size": "SIZE_1024_1024", "outputFormat": "PNG", "background": "TRANSPARENT" } }'

Example request — computer use

curl -X POST "https://superinterface.ai/api/cloud/assistants/{assistantId}/tools" \ -H "Authorization: Bearer YOUR_PRIVATE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "COMPUTER_USE", "computerUseTool": { "displayWidth": 1920, "displayHeight": 1080, "environment": "BROWSER" } }'

Response

Parameter	Type	Description
`tool`	`Tool`	New tool

Example response

{ "tool": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "IMAGE_GENERATION", "imageGenerationTool": { "model": "gpt-image-1", "quality": "HIGH", "size": "SIZE_1024_1024", "outputFormat": "PNG", "background": "TRANSPARENT", "partialImages": 0 }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } }

Errors

The endpoint may return the following errors:

400 Bad Request — tool not available

This error occurs when the tool type is not supported for the assistant's provider configuration.

{ "error": "Tool type IMAGE_GENERATION is not available for this assistant's provider configuration" }

401 Unauthorized

This error occurs if the API key is invalid or missing.

{ "error": "Unauthorized", "message": "Invalid or missing API key" }