Skip to main content
POST
/
v2
/
tools
Create Tool
curl --request POST \
  --url https://api.bland.ai/v2/tools \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "integration": "<string>",
  "action": "<string>",
  "input_schema": {},
  "body": {},
  "speech": "<string>",
  "timeout": 123,
  "cache": true,
  "response_data": [
    {
      "name": "<string>",
      "data": "<string>",
      "context": "<string>"
    }
  ],
  "max_retries": 123,
  "cooldown": 123,
  "resource_id": "<string>",
  "public": true,
  "label": "<string>"
}
'
{
  "name": "SendSlackMessage",
  "description": "Sends a message to a Slack channel",
  "integration": "slack",
  "action": "send_message",
  "input_schema": {
    "type": "object",
    "properties": {
      "channel": { "type": "string" },
      "message": { "type": "string" }
    },
    "required": ["channel", "message"]
  },
  "speech": "Sending that message to Slack now.",
  "timeout": 10000
}

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
name
string
required
The name the AI will see when deciding to use this tool. Must be at least 1 character.Avoid names that conflict with reserved internal tools: input, speak, transfer, switch, wait, finish, press, button, say, pause, record, play, dial, hang.
​
description
string
required
Description of what the tool does. Shown to the AI to help it decide when to use this tool.
​
integration
string
required
The integration key to use. Must be one of: bland-sms, custom-code, slack, salesforce, rest_api, hubspot, calendly, cal-com-v2, notion.
​
action
string
required
The action key to invoke within the integration. To discover available action keys, call GET /v1/integrations/{integration}/actions. Returns 400 ACTION_NOT_FOUND with the list of valid actions if the key is invalid.
​
input_schema
object
Must be a valid OpenAI function calling parameter schema. Defines the parameters the AI will fill in when invoking this tool.
{
  "type": "object",
  "properties": {
    "channel": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": ["channel", "message"]
}
​
body
string | object
Request body template sent to the integration. Supports prompt variables from input_schema (e.g. "{{input.channel}}").
​
speech
string
Text the AI says aloud while executing this tool (e.g. "One moment while I send that message.").
​
timeout
number
Maximum time in milliseconds to wait for the integration to respond. Minimum 1000, maximum 60000.
​
cache
boolean
Whether to cache the tool’s response. Accepts true, false, "true", or "false".
​
response_data
array
Defines which fields to extract from the integration response and make available as prompt variables.
​
max_retries
number
Number of times to retry the tool on failure. Minimum 0, maximum 4.
​
cooldown
number
Seconds to wait between retries. Minimum 1, maximum 30.
​
resource_id
string
UUID of a connected resource (e.g. a Slack workspace or Salesforce org) to scope this tool to. The resource must be active and belong to your account. Returns 404 if the ID is invalid or inactive. To list available resource IDs for an integration, call GET /v1/integrations/{integration}/resources.
​
public
boolean
Whether this tool is publicly visible. Defaults to false.
​
label
string
Optional human-readable label for this tool.

​
Response

​
status
string
"success" on success, "error" on failure.
​
data.id
string
The ID of the newly created tool.
​
errors
null|array
null on success, or a list of error objects if the request failed.
{
  "name": "SendSlackMessage",
  "description": "Sends a message to a Slack channel",
  "integration": "slack",
  "action": "send_message",
  "input_schema": {
    "type": "object",
    "properties": {
      "channel": { "type": "string" },
      "message": { "type": "string" }
    },
    "required": ["channel", "message"]
  },
  "speech": "Sending that message to Slack now.",
  "timeout": 10000
}