Skip to content

Custom API tools (HTTP)

A custom HTTP tool lets the agent call any REST API in your stack — you configure it yourself directly in the admin, no separate development project needed. Typical uses: order status, creating a ticket, verifying a customer, writing to CRM.

If your API is more involved (multi-step authentication, an unusual response format), reach out to your Kanbu contact — we're happy to help you wire it up.

What you configure

In admin under tools you set:

  • Name — an internal identifier for the tool (one word, e.g. order_status).
  • Description — this is how the agent knows when to use the tool. Include rules like "requires an order number" here too.
  • URL and HTTP method — GET, POST, PUT, PATCH, or DELETE. The URL can include a {parameter} placeholder that gets replaced with a value from the conversation.
  • Parameters (path and query) — for each one you set its type (text, number, integer, yes/no), and whether the model fills it in from the conversation or it carries a fixed value you set once in admin that the agent never sees (useful for internal IDs or keys). For model-filled parameters you can also define a closed list of allowed values.
  • Request body (for POST/PUT/PATCH) — you provide a sample JSON body and written instructions; the model generates the entire request body in one shot based on them.
  • Headers — static key/value pairs, for example Authorization: Bearer <token>. Kanbu doesn't have a separate auth-type selector (bearer/API key/basic) — you add it as a regular header. Values are stored encrypted and aren't shown again in admin after saving, only their names.
  • Timeout — 1 to 30 seconds, default 10s.
  • Response mapping (optional) — a path to a field in the response (e.g. data.items) if you want to pass the agent only the relevant part instead of the whole JSON.
  • Agent assignment — a specific selection, or the Available to all agents toggle.

The Test button lets you verify the connection right after setup. After saving, the tool is immediately available in conversations for assigned agents.

Tip for a good description

Write when to use the tool and what it returns. Example: "Use when the customer asks for order status. Requires order number. Returns status and estimated delivery."

Security and limits

  • Requests are protected against calling internal/private addresses and against redirects to them (SSRF protection) — the check runs on every redirect hop, not just the URL you entered.
  • Responses are capped at 1 MB; longer content is truncated.
  • A tool that fails (authentication error, timeout, error status) does not kill the whole conversation — the agent sees the failure as a normal tool result and can retry or continue another way.

Frequently asked questions

  • How do I authenticate the tool?

    Add authentication as a header (most commonly Authorization: Bearer <token>) or as a static query parameter. Kanbu has no separate auth-type selector — it works through regular headers, whose values are stored encrypted.

  • What happens if the endpoint fails or doesn't respond?

    The conversation doesn't end. The agent gets an error message as the tool's result and can retry, use a different tool, or honestly explain the error to the user.

  • How large can the API response be?

    Up to 1 MB; longer responses get truncated. If your API returns a large JSON payload, consider using Response mapping to pass the agent only the relevant part.

  • Can I assign one tool to multiple agents?

    Yes, either select specific agents or turn on Available to all agents.

  • What if my API needs more complex authentication (multiple steps, OAuth)?

    Reach out to your Kanbu contact — a custom HTTP tool is built for static authentication (a header or query parameter). For OAuth, also consider MCP connections, which support OAuth natively.

Related

Back to Connections & toolsContinue to In-chat forms