Tool API: Create, List, Get, Update, Delete

Overview

The Tool API provides full CRUD management for reusable Tool resources that assistants can invoke during a call or chat. This page is the API reference; for a conceptual walkthrough of creating and wiring up a custom function tool, see the Custom Function Tools page. All requests require a Bearer token in the Authorization header.

POST https://api.sulus.ai/tool — creates a reusable tool that assistants can invoke.

Example creating a custom function tool with a server URL:

curl --location 'https://api.sulus.ai/tool' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $SULUS_API_KEY' \
--data '{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retrieves current weather information for any location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city or location to get weather for"
                }
            },
            "required": ["location"]
        }
    },
    "server": {
        "url": "https://your-server.com/tools/weather"
    }
}'

Response: 201 — returns the created Tool object.

GET https://api.sulus.ai/tool — returns reusable tools for your account. Supports the standard pagination/filter query parameters:

GET https://api.sulus.ai/tool/{id} — retrieves a specific tool by its ID.

curl https://api.sulus.ai/tool/<tool-id> \
  -H "Authorization: Bearer $SULUS_API_KEY"

PATCH https://api.sulus.ai/tool/{id} — updates specific fields on an existing tool directly. Include only the fields you want to change; the rest of the tool's configuration remains intact.

curl -X PATCH https://api.sulus.ai/tool/{id} \
  -H "Authorization: Bearer $SULUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "type": "request-start",
        "content": "Hold on a moment while I look that up.",
        "blocking": true
      }
    ]
  }'

A successful request returns 200 with the updated Tool object.

Tool Messages

You can configure messages spoken at different stages of a tool call:

Each message supports content (the text spoken), blocking (boolean, default false — if true, the tool call only fires after the message is spoken), conditions (an optional array of conditions based on tool call arguments that must be met for the message to trigger), and contents (a multilingual alternative to content, one entry per language, which overrides content if provided).

Attaching a Tool to an Assistant

Updating the tool itself (above) is separate from attaching an existing tool to a specific assistant. To do that, update the assistant's model.toolIds field instead:

curl --location --request PATCH 'https://api.sulus.ai/assistant/ASSISTANT_ID' \
--header 'Authorization: Bearer $SULUS_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "model": {
        "provider": "openai",
        "model": "gpt-4o",
        "toolIds": ["your-tool-id-here"]
    }
}'

DELETE https://api.sulus.ai/tool/{id} — deletes a tool by its ID.

curl -X DELETE https://api.sulus.ai/tool/<tool-id> \
  -H "Authorization: Bearer $SULUS_API_KEY"

If a tool you delete is still referenced in an assistant's model.toolIds, remove it from that assistant first so the reference doesn't go stale.

Tool types fall into two groups: those that accept a custom function.parameters schema you define, and built-in types with a platform-controlled schema.

For a conceptual, step-by-step walkthrough of creating a custom function tool and connecting it to your own server, see the Custom Function Tools page. This page is the full CRUD API reference for the Tool resource.

In summary: use POST /tool to create, GET /tool to list, GET /tool/{id} to fetch one, PATCH /tool/{id} to update a tool's own configuration (such as its spoken messages), DELETE /tool/{id} to remove it, and separately, attach a tool to a specific assistant via PATCH /assistant/{id} on model.toolIds.