> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aisky.co.za/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Tools Overview

> Give your AI agent a custom function that hits your own HTTPS endpoint during a live call.

## What HTTP Tools do

HTTP Tools are a Power Tool add-on that lets you wire your AI agent to **your own HTTPS endpoints**. When the AI decides one is the right move during a call, it calls your endpoint, reads the response, and continues the conversation with that answer in hand.

Use them for:

* **Routing decisions**, "Which extension should I transfer this caller to right now?"
* **CRM lookups**, "Is this caller already a customer? What's their last order?"
* **Availability checks**, "Is this Saturday slot still open?"
* **Quote / pricing fetches**, "What's the current quote for SKU X?"
* **Anything only your backend knows** that the agent needs mid-conversation.

A configured HTTP Tool appears to the AI as a regular function, separate name, description, and JSON Schema for its arguments. You can wire as many as you want.

<Note>
  HTTP Tools is a paid add-on. Add **Power Tools** (a rate on request) from your Account → Billing screen to unlock the tool manager.
</Note>

## How it fits with everything else

```
                                ┌─────────────────────────────┐
                                │  Your backend (any stack)   │
                                │  https://api.example.com    │
                                └──────────────▲──────────────┘
                                               │
                                  HMAC-signed  │  HTTPS POST
                                  JSON body    │
   ┌────────────┐    LLM tool   ┌──────────────┴──────────────┐
   │  Caller    │──────call────▶│  AiSky AI agent         │
   │  (phone)   │               │  Custom HTTP Tool descriptor│
   └────────────┘               └─────────────────────────────┘
```

1. The caller talks to your AI agent on the phone.
2. The AI decides a HTTP Tool is the right next move (based on its description).
3. We POST a signed JSON payload to your endpoint.
4. You return whatever data the AI needs (plain text, JSON, HTML, your call).
5. The AI uses that response in its next reply.

Existing transfer mechanisms (PBX transfer, SIP REFER, voicemail drop) stay exactly as they are. The AI chains: **HTTP Tool lookup → transfer to extension X**.

## What's in the box

<CardGroup cols={2}>
  <Card title="Quick start" href="/guides/http-tools/quickstart">
    Configure your first tool in under 5 minutes.
  </Card>

  <Card title="Request & response shape" href="/guides/http-tools/request-and-response">
    What we send you and what we expect back.
  </Card>

  <Card title="Signature verification" href="/guides/http-tools/signature-verification">
    Verify every request is really from us using HMAC-SHA256.
  </Card>

  <Card title="Error codes" href="/guides/http-tools/error-codes">
    Every failure mode, what it means, and how to fix it.
  </Card>

  <Card title="Rate limits" href="/guides/http-tools/rate-limits">
    Per-tenant and per-tool token-bucket budgets.
  </Card>

  <Card title="Security restrictions" href="/guides/http-tools/security-restrictions">
    Why we block private networks, redirects, and binary responses.
  </Card>

  <Card title="Best practices" href="/guides/http-tools/best-practices">
    Designing endpoints the AI can use well.
  </Card>

  <Card title="Code samples" href="/guides/http-tools/code-samples">
    Drop-in handlers for Node.js, Python, PHP, and Go.
  </Card>

  <Card title="Troubleshooting" href="/guides/http-tools/troubleshooting">
    Common failures and how to debug them from the dashboard.
  </Card>
</CardGroup>

## Guarantees and limits

|                         |                                                        |
| ----------------------- | ------------------------------------------------------ |
| Protocol                | HTTPS POST only                                        |
| Total budget per call   | 10 seconds (TLS + DNS + request + response)            |
| Response size           | First 64 KB read; rest discarded                       |
| Redirects               | Not followed (3xx → error)                             |
| Auth options            | Bearer token, HTTP Basic, custom header, or none       |
| Body modes              | Envelope (signed) or passthrough (flat, unsigned)      |
| Signing                 | HMAC-SHA256 over `<ts>.<rawBody>` (envelope mode only) |
| Rate limit (per tenant) | 60 invocations / minute                                |
| Rate limit (per tool)   | 30 invocations / minute                                |

<Note>
  **Two body modes.** By default a tool runs in **envelope mode**: we wrap the arguments in a canonical JSON body, add `X-SmartAlex-*` headers, and sign it with HMAC (see [Signature verification](/guides/http-tools/signature-verification)). If your endpoint is a third-party API that doesn't understand our envelope, switch the tool to **passthrough mode**: you supply a flat JSON body template with `${vault.token}` and `${arg.name}` placeholders, and we POST it as-is with no envelope, no signature, and no `X-SmartAlex-*` headers. Passthrough tools carry their credential inside the template, so the auth scheme is fixed to "none". Passthrough tools can also opt into a short response cache (`cache_ttl_ms`) to skip repeat calls for identical inputs.
</Note>

Everything else, schema authoring, signing-secret rotation, test fires, invocation replays, happens in the dashboard. You should never need to ping support to wire a new tool up; if you do, [tell us](/faq) so we can fix the gap.

## Trust model and data handling

Every invocation forwards `caller_number`, `tenant_id`, `agent_id`, `call_id`, the LLM-provided arguments, and a `timestamp` to your endpoint. Your endpoint runs in your infrastructure under your privacy policy, once data crosses that boundary it's yours to handle.

The body you return is passed verbatim to the AI (subject to a 64 KB cap and a small obfuscation pass on the *dashboard preview only*, never on the wire). Prompt-injection inside the response body is the customer's responsibility, don't put untrusted free-form text in `tool_result` without sanitization on your side.