Log InContact
Browse the docs

API reference

Tools

Functions an agent calls during the call: your HTTPS endpoint, a search of web pages, an SMS or an email. A tool is attached to an agent through its call flow.

GET/v1/toolsPOST/v1/toolsGET/v1/tools/{toolId}PATCH/v1/tools/{toolId}DELETE/v1/tools/{toolId}

List tools

GET/v1/tools
Bearer API key

List every tool of the account, sorted by name.

A tool is a function the agent can call during a conversation. Four types are available:

  • custom — POST the arguments the agent collected to your own HTTPS endpoint (OpenAI function calling: config.parameters is the JSON Schema of the arguments).
  • query — let the agent search the content of one or more web pages to answer a question.
  • sendSms — send a templated SMS during the call (to a fixed number, or to the caller when config.to is omitted).
  • sendEmail — send a templated email during the call; the agent's notes are passed as the notes argument.

Transferring the call to a phone number, handing over to another agent and ending the call are not tools: they are nodes of the agent diagram (forwardCall, forwardAgent, endCall in GET /v1/agents/{agentId}). MCP servers, code execution and transfer cancellation are not available.

A tool is attached to an agent by referencing it in a knowHow node prompt of the agent diagram (see AgentDiagram).

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Responses

Tools retrieved successfully

dataobject[]required
Show the variants
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedcustom
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlstring<uri>required

HTTPS endpoint that receives a POST with the collected arguments.

example https://example.com/api/orders/lookup
apiTimeoutinteger

Seconds to wait for the endpoint (default 10).

from 1 to 15example 10
parametersobject

JSON Schema of the arguments the agent collects before calling the tool, in the OpenAI function calling format. The root must be an object.

Show child attributes
typeenum<string>required
Allowedobject
propertiesobjectrequired
requiredstring[]
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedquery
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlsobject[]required

Web pages the agent may search.

Show child attributes
urlstring<uri>required
example https://example.com/faq
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendSms
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
bodystringrequired

SMS text.

1 to 1600 charactersexample Thanks for calling! Your appointment is confirmed.
tostring

Recipient in E.164 format. Omit to send the SMS to the caller.

pattern ^\+[1-9]\d{6,14}$example +33612345678
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendEmail
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
subjectstringrequired

Email subject. <email-placeholder-node variablename="…">…</email-placeholder-node> tokens are replaced at call time; variables: contact.email, contact.firstName, contact.lastName, caller.phoneNumber, notes.

1 to 998 charactersexample Your order <email-placeholder-node variablename="notes">notes</email-placeholder-node>
bodystringrequired

HTML body. Accepts the same variable tokens as the subject.

at least 1 characterexample <p>Summary of the call: <email-placeholder-node variablename="notes">notes</email-placeholder-node></p>
tostring[]required

Recipients: email addresses, or <email-placeholder-node variablename="contact.email">contact email</email-placeholder-node> to email the contact on the call.

notesInstructionsstring

What the agent should put in the notes argument it passes to the tool.

example Summarise the caller's request in two sentences.
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z

Unauthorized

errorstringrequired

Internal server error

errorstringrequired
GET
curl "https://api.callshift.ai/v1/tools" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/tools", {
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
const data = await res.json();
import os
import requests

res = requests.get(
    "https://api.callshift.ai/v1/tools",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.json())
Response
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "custom",
      "name": "Check order",
      "description": "Looks up an order by its number and returns its status.",
      "config": {
        "url": "https://example.com/api/orders/lookup",
        "apiTimeout": 10,
        "parameters": {
          "type": "object",
          "properties": {
            "orderNumber": {
              "type": "string",
              "description": "The order number, e.g. ORD-1234"
            }
          },
          "required": [
            "orderNumber"
          ]
        },
        "async": false,
        "messages": {
          "requestStart": {
            "content": "Let me check that for you.",
            "blocking": true
          },
          "requestFailed": {
            "content": "I could not check that right now."
          }
        }
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}
{
  "error": "Authentication error"
}
{
  "error": "Internal server error"
}

Create a tool

POST/v1/tools
Bearer API key

Create a tool of one of the four types. The body is discriminated by type; each variant documents a complete example.

A tool is a function the agent can call during a conversation. Four types are available:

  • custom — POST the arguments the agent collected to your own HTTPS endpoint (OpenAI function calling: config.parameters is the JSON Schema of the arguments).
  • query — let the agent search the content of one or more web pages to answer a question.
  • sendSms — send a templated SMS during the call (to a fixed number, or to the caller when config.to is omitted).
  • sendEmail — send a templated email during the call; the agent's notes are passed as the notes argument.

Transferring the call to a phone number, handing over to another agent and ending the call are not tools: they are nodes of the agent diagram (forwardCall, forwardAgent, endCall in GET /v1/agents/{agentId}). MCP servers, code execution and transfer cancellation are not available.

A tool is attached to an agent by referencing it in a knowHow node prompt of the agent diagram (see AgentDiagram).

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Body application/json

typeenum<string>required
Allowedcustom
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlstring<uri>required

HTTPS endpoint that receives a POST with the collected arguments.

example https://example.com/api/orders/lookup
apiTimeoutinteger

Seconds to wait for the endpoint (default 10).

from 1 to 15example 10
parametersobject

JSON Schema of the arguments the agent collects before calling the tool, in the OpenAI function calling format. The root must be an object.

Show child attributes
typeenum<string>required
Allowedobject
propertiesobjectrequired
requiredstring[]
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
typeenum<string>required
Allowedquery
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlsobject[]required

Web pages the agent may search.

Show child attributes
urlstring<uri>required
example https://example.com/faq
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
typeenum<string>required
AllowedsendSms
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
bodystringrequired

SMS text.

1 to 1600 charactersexample Thanks for calling! Your appointment is confirmed.
tostring

Recipient in E.164 format. Omit to send the SMS to the caller.

pattern ^\+[1-9]\d{6,14}$example +33612345678
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
typeenum<string>required
AllowedsendEmail
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
subjectstringrequired

Email subject. <email-placeholder-node variablename="…">…</email-placeholder-node> tokens are replaced at call time; variables: contact.email, contact.firstName, contact.lastName, caller.phoneNumber, notes.

1 to 998 charactersexample Your order <email-placeholder-node variablename="notes">notes</email-placeholder-node>
bodystringrequired

HTML body. Accepts the same variable tokens as the subject.

at least 1 characterexample <p>Summary of the call: <email-placeholder-node variablename="notes">notes</email-placeholder-node></p>
tostring[]required

Recipients: email addresses, or <email-placeholder-node variablename="contact.email">contact email</email-placeholder-node> to email the contact on the call.

notesInstructionsstring

What the agent should put in the notes argument it passes to the tool.

example Summarise the caller's request in two sentences.
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000

Responses

Tool created successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedcustom
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlstring<uri>required

HTTPS endpoint that receives a POST with the collected arguments.

example https://example.com/api/orders/lookup
apiTimeoutinteger

Seconds to wait for the endpoint (default 10).

from 1 to 15example 10
parametersobject

JSON Schema of the arguments the agent collects before calling the tool, in the OpenAI function calling format. The root must be an object.

Show child attributes
typeenum<string>required
Allowedobject
propertiesobjectrequired
requiredstring[]
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedquery
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlsobject[]required

Web pages the agent may search.

Show child attributes
urlstring<uri>required
example https://example.com/faq
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendSms
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
bodystringrequired

SMS text.

1 to 1600 charactersexample Thanks for calling! Your appointment is confirmed.
tostring

Recipient in E.164 format. Omit to send the SMS to the caller.

pattern ^\+[1-9]\d{6,14}$example +33612345678
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendEmail
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
subjectstringrequired

Email subject. <email-placeholder-node variablename="…">…</email-placeholder-node> tokens are replaced at call time; variables: contact.email, contact.firstName, contact.lastName, caller.phoneNumber, notes.

1 to 998 charactersexample Your order <email-placeholder-node variablename="notes">notes</email-placeholder-node>
bodystringrequired

HTML body. Accepts the same variable tokens as the subject.

at least 1 characterexample <p>Summary of the call: <email-placeholder-node variablename="notes">notes</email-placeholder-node></p>
tostring[]required

Recipients: email addresses, or <email-placeholder-node variablename="contact.email">contact email</email-placeholder-node> to email the contact on the call.

notesInstructionsstring

What the agent should put in the notes argument it passes to the tool.

example Summarise the caller's request in two sentences.
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z

Invalid request body

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

Internal server error

errorstringrequired
POST
curl -X POST "https://api.callshift.ai/v1/tools" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "Check order",
    "description": "Looks up an order by its number and returns its status.",
    "config": {
      "url": "https://example.com/api/orders/lookup",
      "apiTimeout": 10,
      "parameters": {
        "type": "object",
        "properties": {
          "orderNumber": {
            "type": "string",
            "description": "The order number, e.g. ORD-1234"
          }
        },
        "required": [
          "orderNumber"
        ]
      },
      "messages": {
        "requestStart": {
          "content": "Let me look that up."
        }
      }
    }
  }'
const res = await fetch("https://api.callshift.ai/v1/tools", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "type": "custom",
    "name": "Check order",
    "description": "Looks up an order by its number and returns its status.",
    "config": {
      "url": "https://example.com/api/orders/lookup",
      "apiTimeout": 10,
      "parameters": {
        "type": "object",
        "properties": {
          "orderNumber": {
            "type": "string",
            "description": "The order number, e.g. ORD-1234"
          }
        },
        "required": [
          "orderNumber"
        ]
      },
      "messages": {
        "requestStart": {
          "content": "Let me look that up."
        }
      }
    }
  }),
});
const data = await res.json();
import os
import requests

res = requests.post(
    "https://api.callshift.ai/v1/tools",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
    json={
        "type": "custom",
        "name": "Check order",
        "description": "Looks up an order by its number and returns its status.",
        "config": {
            "url": "https://example.com/api/orders/lookup",
            "apiTimeout": 10,
            "parameters": {
                "type": "object",
                "properties": {
                    "orderNumber": {
                        "type": "string",
                        "description": "The order number, e.g. ORD-1234",
                    },
                },
                "required": [
                    "orderNumber",
                ],
            },
            "messages": {
                "requestStart": {
                    "content": "Let me look that up.",
                },
            },
        },
    },
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "custom",
  "name": "Check order",
  "description": "Looks up an order by its number and returns its status.",
  "config": {
    "url": "https://example.com/api/orders/lookup",
    "apiTimeout": 10,
    "parameters": {
      "type": "object",
      "properties": {
        "orderNumber": {
          "type": "string",
          "description": "The order number, e.g. ORD-1234"
        }
      },
      "required": [
        "orderNumber"
      ]
    },
    "async": false,
    "messages": {
      "requestStart": {
        "content": "Let me check that for you.",
        "blocking": true
      },
      "requestFailed": {
        "content": "I could not check that right now."
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "Internal server error"
}

Get a tool

GET/v1/tools/{toolId}
Bearer API key

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

toolIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Responses

Tool retrieved successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedcustom
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlstring<uri>required

HTTPS endpoint that receives a POST with the collected arguments.

example https://example.com/api/orders/lookup
apiTimeoutinteger

Seconds to wait for the endpoint (default 10).

from 1 to 15example 10
parametersobject

JSON Schema of the arguments the agent collects before calling the tool, in the OpenAI function calling format. The root must be an object.

Show child attributes
typeenum<string>required
Allowedobject
propertiesobjectrequired
requiredstring[]
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedquery
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlsobject[]required

Web pages the agent may search.

Show child attributes
urlstring<uri>required
example https://example.com/faq
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendSms
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
bodystringrequired

SMS text.

1 to 1600 charactersexample Thanks for calling! Your appointment is confirmed.
tostring

Recipient in E.164 format. Omit to send the SMS to the caller.

pattern ^\+[1-9]\d{6,14}$example +33612345678
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendEmail
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
subjectstringrequired

Email subject. <email-placeholder-node variablename="…">…</email-placeholder-node> tokens are replaced at call time; variables: contact.email, contact.firstName, contact.lastName, caller.phoneNumber, notes.

1 to 998 charactersexample Your order <email-placeholder-node variablename="notes">notes</email-placeholder-node>
bodystringrequired

HTML body. Accepts the same variable tokens as the subject.

at least 1 characterexample <p>Summary of the call: <email-placeholder-node variablename="notes">notes</email-placeholder-node></p>
tostring[]required

Recipients: email addresses, or <email-placeholder-node variablename="contact.email">contact email</email-placeholder-node> to email the contact on the call.

notesInstructionsstring

What the agent should put in the notes argument it passes to the tool.

example Summarise the caller's request in two sentences.
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z

Unauthorized

errorstringrequired

Tool not found

errorstringrequired

Internal server error

errorstringrequired
GET
curl "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000", {
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
const data = await res.json();
import os
import requests

res = requests.get(
    "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "custom",
  "name": "Check order",
  "description": "Looks up an order by its number and returns its status.",
  "config": {
    "url": "https://example.com/api/orders/lookup",
    "apiTimeout": 10,
    "parameters": {
      "type": "object",
      "properties": {
        "orderNumber": {
          "type": "string",
          "description": "The order number, e.g. ORD-1234"
        }
      },
      "required": [
        "orderNumber"
      ]
    },
    "async": false,
    "messages": {
      "requestStart": {
        "content": "Let me check that for you.",
        "blocking": true
      },
      "requestFailed": {
        "content": "I could not check that right now."
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "error": "Authentication error"
}
{
  "error": "Tool not found"
}
{
  "error": "Internal server error"
}

Update a tool

PATCH/v1/tools/{toolId}
Bearer API key

Change the name, the description or part of the config. Each top-level config field sent replaces the stored one as a whole (send all of messages or parameters to change one entry), omitted fields keep their value, and null clears an optional field. The resulting config is validated against the tool's type.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

toolIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Body application/json

namestring

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | null

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobject

Top-level fields to change in the tool's config, each replacing the stored value as a whole (null clears it). They are merged over the stored config and the result is validated against the schema of the tool's type (CustomToolConfig, QueryToolConfig, SendSmsToolConfig or SendEmailToolConfig). The type itself cannot change: delete the tool and create a new one.

Responses

Tool updated successfully

idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedcustom
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlstring<uri>required

HTTPS endpoint that receives a POST with the collected arguments.

example https://example.com/api/orders/lookup
apiTimeoutinteger

Seconds to wait for the endpoint (default 10).

from 1 to 15example 10
parametersobject

JSON Schema of the arguments the agent collects before calling the tool, in the OpenAI function calling format. The root must be an object.

Show child attributes
typeenum<string>required
Allowedobject
propertiesobjectrequired
requiredstring[]
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
Allowedquery
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
urlsobject[]required

Web pages the agent may search.

Show child attributes
urlstring<uri>required
example https://example.com/faq
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendSms
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
bodystringrequired

SMS text.

1 to 1600 charactersexample Thanks for calling! Your appointment is confirmed.
tostring

Recipient in E.164 format. Omit to send the SMS to the caller.

pattern ^\+[1-9]\d{6,14}$example +33612345678
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z
idstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000
typeenum<string>required
AllowedsendEmail
namestringrequired

Name shown in the dashboard. Its camelCase form is the function name the agent calls, so keep it unique per tenant. Agent prompts reference a tool by that function name: renaming a tool detaches it from the agents that use it until their <tool-node functionname> is updated.

1 to 40 charactersexample Check order
descriptionstring | nullrequired

Tells the agent what the tool does and when to use it.

up to 1000 charactersexample Looks up an order by its number and returns its status.
configobjectrequired
Show child attributes
subjectstringrequired

Email subject. <email-placeholder-node variablename="…">…</email-placeholder-node> tokens are replaced at call time; variables: contact.email, contact.firstName, contact.lastName, caller.phoneNumber, notes.

1 to 998 charactersexample Your order <email-placeholder-node variablename="notes">notes</email-placeholder-node>
bodystringrequired

HTML body. Accepts the same variable tokens as the subject.

at least 1 characterexample <p>Summary of the call: <email-placeholder-node variablename="notes">notes</email-placeholder-node></p>
tostring[]required

Recipients: email addresses, or <email-placeholder-node variablename="contact.email">contact email</email-placeholder-node> to email the contact on the call.

notesInstructionsstring

What the agent should put in the notes argument it passes to the tool.

example Summarise the caller's request in two sentences.
asyncboolean

When true the agent does not wait for the result and continues the conversation.

example false
messagesobject

Optional sentences the agent speaks around the tool call. An omitted requestStart or requestDelayed gets a default; one sent without content is silent.

Show child attributes
requestStartobject

Spoken when the tool call starts.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
blockingboolean

Wait for the message to be spoken before calling the tool.

requestCompleteobject

Spoken when the tool call succeeds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
roleenum<string>
Allowedassistantsystem
requestFailedobject

Spoken when the tool call fails.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
requestDelayedobject

Spoken when the tool has not answered after timingMilliseconds.

Show child attributes
contentstring

What the agent says, in the agent's language.

up to 1000 characters
timingMillisecondsinteger
from 1000 to 30000
createdAtstringrequired
example 2026-01-01T00:00:00.000Z
updatedAtstring | nullrequired
example 2026-01-01T00:00:00.000Z

Invalid request body

successenum<boolean>required
Allowedfalse
errorobjectrequired
Show child attributes
nameenum<string>required
AllowedZodError
issuesobject[]required
Show child attributes
codestringrequired
example invalid_enum_value
pathstring | number[]required
messagestringrequired
example Invalid email

Unauthorized

errorstringrequired

Tool not found

errorstringrequired

Internal server error

errorstringrequired
PATCH
curl -X PATCH "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "url": "https://example.com/api/v2/orders/lookup"
    }
  }'
const res = await fetch("https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "config": {
      "url": "https://example.com/api/v2/orders/lookup"
    }
  }),
});
const data = await res.json();
import os
import requests

res = requests.patch(
    "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
    json={
        "config": {
            "url": "https://example.com/api/v2/orders/lookup",
        },
    },
)
print(res.json())
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "custom",
  "name": "Check order",
  "description": "Looks up an order by its number and returns its status.",
  "config": {
    "url": "https://example.com/api/orders/lookup",
    "apiTimeout": 10,
    "parameters": {
      "type": "object",
      "properties": {
        "orderNumber": {
          "type": "string",
          "description": "The order number, e.g. ORD-1234"
        }
      },
      "required": [
        "orderNumber"
      ]
    },
    "async": false,
    "messages": {
      "requestStart": {
        "content": "Let me check that for you.",
        "blocking": true
      },
      "requestFailed": {
        "content": "I could not check that right now."
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "invalid_enum_value",
        "path": [
          "contacts",
          0,
          "email"
        ],
        "message": "Invalid email"
      }
    ]
  }
}
{
  "error": "Authentication error"
}
{
  "error": "Tool not found"
}
{
  "error": "Internal server error"
}

Delete a tool

DELETE/v1/tools/{toolId}
Bearer API key

Delete a tool. Refused with a 409 while an agent prompt still references it, unless force=true.

Authorization

Authorizationstringrequired

Bearer <API key>, a key created at app.callshift.ai/api-keys.

Path parameters

toolIdstring<uuid>required
example 550e8400-e29b-41d4-a716-446655440000

Query parameters

forceenum<string>

Delete the tool even if agents still reference it. Their prompts keep the reference, which is skipped when the agent is built.

default "false"example false
Allowedtruefalse

Responses

Tool deleted successfully

No content.

Unauthorized

errorstringrequired

Tool not found

errorstringrequired

The tool is referenced by at least one agent

errorenum<string>required
AllowedTool is attached to agents
agentsobject[]required
Show child attributes
idstring<uuid>required
namestringrequired

Internal server error

errorstringrequired
DELETE
curl -X DELETE "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY"
const res = await fetch("https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CALLSHIFT_API_KEY}`,
  },
});
console.log(res.status); // 204
import os
import requests

res = requests.delete(
    "https://api.callshift.ai/v1/tools/550e8400-e29b-41d4-a716-446655440000",
    headers={"Authorization": f"Bearer {os.environ['CALLSHIFT_API_KEY']}"},
)
print(res.status_code)  # 204
Response
No content
{
  "error": "Authentication error"
}
{
  "error": "Tool not found"
}
{
  "error": "Tool is attached to agents",
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Alice"
    }
  ]
}
{
  "error": "Internal server error"
}