> ## 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 Quickstart

> From "I want a tool" to "the AI calls my backend" in under 5 minutes.

The whole flow happens inside the dashboard, no CLI, no deploys on our end, no support ticket.

## Prerequisites

* Power Tools add-on is active on your account (Account → Billing → Add-ons → Power Tools).
* An HTTPS endpoint somewhere (real backend, ngrok tunnel, Cloudflare tunnel, anything reachable on the public internet over TLS).
* A super-admin or admin role on the tenant so the dashboard exposes the tool manager.

<Note>
  Building locally? Expose your local server through a tunnel:

  ```bash theme={null}
  ngrok http 3000
  # → https://abc-123.ngrok-free.app
  ```

  Use the tunnel URL as your endpoint. Switch to your real URL when you deploy.
</Note>

## 1. Open the tool manager

In the dashboard:

1. Open **Agent Studio**.
2. Pick the agent that should have the new tool.
3. Open the **Tools** tab.
4. Find the **Custom HTTP Tools** card under Power Tools and click **Manage**.

You'll land in a dialog. First time through, it's empty.

## 2. Pick a starting point

Two paths:

<Tabs>
  <Tab title="Starter template">
    Pre-fills a `lookup_routing` tool that takes a `query` string. Good if you're new to JSON Schema or just want to see what a working tool looks like before customizing.
  </Tab>

  <Tab title="Start from scratch">
    Blank form. Fill in name, description, URL, and JSON Schema yourself.
  </Tab>
</Tabs>

## 3. Configure

Fill in (or edit) these fields:

<ResponseField name="Name" type="string" required>
  Lowercase, snake\_case identifier, 3-64 characters. This is what the AI sees as the function name when deciding whether to call your tool. Examples: `lookup_routing`, `check_balance`, `fetch_order_status`.

  Reserved names (built-in tools like `transfer_to_pbx`, `end_call`, etc.) are blocked.
</ResponseField>

<ResponseField name="Description" type="string" required>
  10-500 characters. The AI uses this verbatim to decide *when* to call your tool. Write it like a one-paragraph briefing for a new colleague: what does this tool answer, and when should the AI reach for it?

  Bad: `Looks up routing.`

  Good: `Ask our backend which PBX extension should take the caller. Pass the caller's intent (e.g. "billing", "sales", "after-hours emergency") as 'query'. Returns an extension number and a one-line hint.`
</ResponseField>

<ResponseField name="URL" type="string" required>
  Full `https://...` endpoint. We validate live as you type:

  * Must be `https://` (no `http://`)
  * No credentials in the URL (`https://user:pass@...`), use the auth field below
  * No private IPs (10.x, 192.168.x, localhost, AWS metadata, etc.)
  * No links into our own infrastructure (`*.aisky.co.za`, `*.supabase.co`, `*.amazonaws.com`)
  * Max 2048 characters

  See [Security restrictions](/guides/http-tools/security-restrictions) for the full ruleset.
</ResponseField>

<ResponseField name="Parameters" type="JSON Schema" required>
  A standard JSON Schema describing what arguments the AI passes. The dashboard editor validates as you type and shows a live preview of what the AI will see.

  Minimal example:

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "What the caller wants in plain English"
      }
    },
    "required": ["query"]
  }
  ```

  If you have an example arguments object, hit **Generate from example** to scaffold a schema automatically.
</ResponseField>

<ResponseField name="Authentication" type="enum">
  Pick one:

  * **Bearer token**, we send `Authorization: Bearer <your-token>`. Most common.
  * **HTTP Basic**, enter a username and password; we send `Authorization: Basic <base64(user:pass)>`.
  * **Custom header**, we send `<Header-Name>: <your-token>`. Useful when your API expects `X-API-Key` or similar.
  * **None**, no auth header. Sign-only (our HMAC signature is still sent).

  Tokens are stored encrypted in Vault. The dashboard never displays them after save.
</ResponseField>

<Note>
  Calling a third-party API that has its own request format? Flip the tool into **passthrough mode**: instead of our signed envelope, you supply a flat JSON body template with `${vault.token}` and `${arg.name}` placeholders, and we POST it verbatim. Passthrough tools fix the auth scheme to "none" (the credential lives in the template). See [Request and response shape](/guides/http-tools/request-and-response#passthrough-mode-flat-body).
</Note>

<ResponseField name="Active" type="boolean">
  Toggle off if you want to keep the configuration but stop the AI from calling the tool.
</ResponseField>

## 4. Save and save the signing secret

The **first** time you save *any* HTTP Tool on this tenant, the dashboard generates a per-tenant signing secret and shows it in a modal.

<Warning>
  **This is the only time we display the signing secret.** Copy it into your environment / secrets store before clicking "I've saved it". If you lose it, rotate (which invalidates the old secret immediately) and update your endpoint with the new one.
</Warning>

The secret has the prefix `shs_` and is 64 hex characters (32 bytes / 256 bits). You'll use it on your endpoint to verify every request, see [Signature verification](/guides/http-tools/signature-verification).

## 5. Test fire

Hop to the **Test** tab of the tool you just configured:

1. The form pre-fills sample arguments matching your schema.
2. Click **Send test**.
3. You'll see the full request, URL, headers (including the live HMAC signature), body, and your endpoint's response, status code, and latency.
4. Click **Copy as curl** to replay the exact same call from your terminal. Useful for verifying signature math on your side.

If anything fails, the result panel shows the exact error code with a one-line explanation. Cross-reference with [Error codes](/guides/http-tools/error-codes).

## 6. Verify the AI can see it

Back in Agent Studio, the **Custom HTTP Tools** card should now show "Active" with a count of `1 configured`. The agent automatically picks up the descriptor on the next call, no redeploy.

Place a test call and ask something that should trigger your tool. The dashboard's **Invocations** panel will show the live request 1-2 seconds after the call ends, with full payload, response, latency, and the signature we sent.

## 7. Done

That's the whole flow. From here:

* Add more tools (different names, same signing secret).
* Tweak descriptions to nudge the AI toward calling your tool in different scenarios.
* Watch the invocations panel for failures and click into any row to see the full request / response and a "Replay as curl" button.

<Card title="Next: Request & response shape" href="/guides/http-tools/request-and-response">
  Exact body, headers, and what you should return.
</Card>