> ## Documentation Index
> Fetch the complete documentation index at: https://api.scalysis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an API tool

> Let your agent call your own API during a call.

An API tool lets your agent fetch or send data during a call. For example, it can check stock, book a slot or look up a loyalty balance.

You need a public `https://` endpoint that answers within 30 seconds.

**1. Create the tool**

Send the endpoint, method, any auth header and the values the agent should collect.

```bash theme={null}
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",
    "headers": [{ "key": "X-Api-Key", "value": "YOUR_STORE_KEY", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions" }]
  }'
```

Save `tool.id` from the response.

**2. Attach it to an agent**

In the dashboard, open the agent, go to **Knowledge & tools**, select the tool and save.

**3. Tell the agent when to use it**

Add a line to the agent's instructions, like "If the customer asks about stock, check it before answering."

**4. Test it**

[Chat with the agent](https://api.scalysis.com/guides/chat-with-an-agent.md) and ask a question that needs the tool.

## What your API receives

By default, the parameters the agent collected plus your preset values, as JSON. To control the exact body, set `bodyTemplate`:

```json theme={null}
{ "sku": "{{sku}}", "phone": "{{call.phone_number}}" }
```

| Placeholder | Filled with |
| - | - |
| `{{sku}}` | A parameter the agent collected |
| `{{call.phone_number}}` | The customer's number |
| `{{call.your_variable}}` | A variable you sent when starting the call |
| `{{collected.field}}` | Something the agent gathered earlier in the call |

What your API returns is read by the agent. Keep it short and plain, like `{ "in_stock": true, "price": 1299 }`.

## Tips

* Mark API keys `secret: true`. They are never shown again.
* Write `description` as a rule: when to use the tool, not what it is.
* Set `speakWhileWaiting` for slow APIs so the customer isn't left in silence.
* Use `presetParameters` with `{{call.phone_number}}` to send the caller's number without asking.

> [card] [API reference](https://api.scalysis.com/api-reference/tools/create.md)
>
> Every field, with examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.