Create a tool

curl -X POST https://app.scalysis.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "url": "https://api.yourstore.com/stock",
    "method": "POST",
    "headers": [{ "key": "X-Api-Key", "value": "YOUR_STORE_KEY", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions" }],
    "presetParameters": [{ "name": "phone", "value": "{{call.phone_number}}" }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check."
  }'

{
  "success": true,
  "action": "create_tool",
  "tool": {
    "id": 512,
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "method": "POST",
    "url": "https://api.yourstore.com/stock",
    "headers": [{ "key": "X-Api-Key", "value": "••••••••", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions", "required": true }],
    "presetParameters": [{ "name": "phone", "type": "string", "value": "{{call.phone_number}}", "required": true }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "bodyFormat": "json",
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check.",
    "createdAt": "2026-10-26T17:19:29.374Z",
    "updatedAt": "2026-10-26T17:19:29.374Z"
  }
}

{
  "success": false,
  "error": "url must be a public internet address.",
  "error_code": "INVALID_REQUEST"
}

Creates a tool your agent can use mid-call, like checking stock or booking a slot. The tool is ready right away. Attach it to an agent in the dashboard: open the agent, go to Knowledge & tools, select the tool and save.

Body

string

required

Tool name. Up to 128 characters.

string

required

When the agent should use this tool. Be specific, for example “Use when the customer asks if an item is in stock.” Up to 2000 characters.

string

required

Your endpoint. Must start with https:// and be a public address. No username or password in the URL.

string

default:"POST"

GET, POST, PUT, PATCH or DELETE.

array

Headers sent with every request. Up to 20.

Show header

string

required

Header name, like X-Api-Key.

string

required

Header value. Up to 4000 characters.

boolean

default:"false"

Set true for API keys. Secret values are never returned. Responses show ••••••••.

array

Values the agent collects from the customer and sends. Up to 30.

Show parameter

string

required

Letters, numbers and underscores. Must start with a letter or underscore. Up to 64 characters.

string

default:"string"

string, number or boolean.

string

required

What the value is. The agent reads this.

boolean

default:"true"

Whether the agent must have this value before calling.

array

Values sent every time, without asking the customer. Up to 30.

Show preset

string

required

Same rules as parameters. Names must be unique across both lists.

string

default:"string"

string, number or boolean.

string

required

Fixed text, or a placeholder: {{call.phone_number}} or {{call.your_variable}} for call details, {{collected.field}} for something gathered earlier in the call.

boolean

default:"true"

Whether this value must be present.

object

Exact JSON body to send. Use {{parameter_name}} to insert a parameter, and {{call.x}} or {{collected.x}} for call details. Leave out to use the default body.

string

default:"json"

json or form.

number

default:"10000"

How long to wait for your API, from 1000 to 30000.

string

A short line the agent says while your API runs, like “One moment, let me check.” Up to 500 characters.

curl -X POST https://app.scalysis.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "url": "https://api.yourstore.com/stock",
    "method": "POST",
    "headers": [{ "key": "X-Api-Key", "value": "YOUR_STORE_KEY", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions" }],
    "presetParameters": [{ "name": "phone", "value": "{{call.phone_number}}" }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check."
  }'

{
  "success": true,
  "action": "create_tool",
  "tool": {
    "id": 512,
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "method": "POST",
    "url": "https://api.yourstore.com/stock",
    "headers": [{ "key": "X-Api-Key", "value": "••••••••", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions", "required": true }],
    "presetParameters": [{ "name": "phone", "type": "string", "value": "{{call.phone_number}}", "required": true }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "bodyFormat": "json",
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check.",
    "createdAt": "2026-10-26T17:19:29.374Z",
    "updatedAt": "2026-10-26T17:19:29.374Z"
  }
}

{
  "success": false,
  "error": "url must be a public internet address.",
  "error_code": "INVALID_REQUEST"
}

Response

number

Save this. Use it to read, edit or delete the tool.

Errors

Status	`error_code`	Meaning
`400`	`INVALID_REQUEST`	A field is wrong. `error` usually says which.
`409`	`LIMIT_REACHED`	You have 100 tools. Delete one first.
`503`	`SERVICE_UNAVAILABLE`	Try again. List tools first so you don’t create it twice.

curl -X POST https://app.scalysis.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "url": "https://api.yourstore.com/stock",
    "method": "POST",
    "headers": [{ "key": "X-Api-Key", "value": "YOUR_STORE_KEY", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions" }],
    "presetParameters": [{ "name": "phone", "value": "{{call.phone_number}}" }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check."
  }'

{
  "success": true,
  "action": "create_tool",
  "tool": {
    "id": 512,
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "method": "POST",
    "url": "https://api.yourstore.com/stock",
    "headers": [{ "key": "X-Api-Key", "value": "••••••••", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions", "required": true }],
    "presetParameters": [{ "name": "phone", "type": "string", "value": "{{call.phone_number}}", "required": true }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "bodyFormat": "json",
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check.",
    "createdAt": "2026-10-26T17:19:29.374Z",
    "updatedAt": "2026-10-26T17:19:29.374Z"
  }
}

{
  "success": false,
  "error": "url must be a public internet address.",
  "error_code": "INVALID_REQUEST"
}

Calls

Orders

Campaigns

Account

Agents

Agent chat

Tools

Body

Response

Errors

​Body

​Response

​Errors

Body

Response

Errors