AI Tools API

These endpoints use your API key and manage the same tools as the AI Tools page in the dashboard.

import { KerAbieClient } from '@kerabie/sdk';

const kerabie = new KerAbieClient({ apiKey: process.env.KERABIE_API_KEY });

A tool is an API of yours that the chatbot may call mid-conversation: check stock, validate an address, look up an order, book a slot. The AI reads the tool's description to decide when to call it, collects the parameters from the customer, calls your endpoint, and uses the answer in its reply.

Three built-in tools are always available and need no setup: save_memory, get_memory and escalate_to_agent.

How a call works

Your endpoint has 8 seconds to answer. If you set a responsePath such as data.message, only that part of a JSON reply is shown to the AI; otherwise it sees the whole reply (cut at 8,000 characters). A non-2xx answer, a timeout or a network error is reported to the AI as a failure, and it will say it couldn't complete the request.

Rules

• Public addresses only. Endpoints on localhost, private networks or cloud metadata addresses are rejected, and redirects are not followed. Use the final URL.
• Secrets are write-only. authConfig values are stored when you send them and never returned. On update, leave a secret out (or blank) to keep the stored one.
• Plan limit. Your plan sets how many tools you can have. stats.limit is -1 when AI tools aren't on your plan and 0 when unlimited. create and duplicate return 403 when it is full. If you downgrade, the chatbot keeps using your oldest enabled tools up to the new limit.
• Function names are snake_case and unique in your organisation (409 if taken).
• Up to 20 parameters and 10 custom headers per tool.

List tools

GET /v1/ai-tools

const { tools, stats } = await kerabie.aiTools.list();

{
  "tools": [
    {
      "id": 1,
      "name": "check_availability",
      "displayName": "Check availability",
      "description": "Use this when a customer asks if a specific item is in stock.",
      "parameters": [
        { "name": "sku", "type": "string", "description": "Product SKU the customer mentioned", "required": true }
      ],
      "endpoint": "https://api.yourstore.com/inventory/check",
      "method": "GET",
      "authType": "bearer",
      "responsePath": "data.message",
      "enabled": true,
      "createdAt": "2026-10-01T09:00:00.000Z",
      "updatedAt": "2026-10-01T09:00:00.000Z",
      "usage": { "calls": 142, "failures": 6, "lastUsedAt": "2026-10-06T12:30:00.000Z" }
    }
  ],
  "stats": { "total": 1, "active": 1, "calls": 142, "successRate": 96, "limit": 5 }
}

usage and stats.calls cover the last 30 days. successRate is null when there were no calls.

Get a tool

GET /v1/ai-tools/:id

Returns the tool with authConfig (names only, secrets come back empty), headers and hasSecret.

Create a tool

POST /v1/ai-tools

const { tool } = await kerabie.aiTools.create({
  name: 'check_availability',
  displayName: 'Check availability',
  description: 'Use this when a customer asks if a specific item is in stock.',
  endpoint: 'https://api.yourstore.com/inventory/check',
  method: 'GET',
  authType: 'bearer',
  authConfig: { token: process.env.STORE_API_TOKEN },
  responsePath: 'data.message',
  parameters: [{ name: 'sku', type: 'string', description: 'Product SKU the customer mentioned' }],
});

Returns { "tool": { "id": 12 } }.

Update a tool

PATCH /v1/ai-tools/:id

await kerabie.aiTools.update(12, { enabled: false });

Send only what you want to change. Changing authType needs the new secrets in authConfig.

Duplicate a tool

POST /v1/ai-tools/:id/duplicate

Creates a copy named <name>_copy that starts switched off, so you can edit it before the AI can use it.

Delete a tool

DELETE /v1/ai-tools/:id

Test a tool

POST /v1/ai-tools/:id/test

const result = await kerabie.aiTools.test(12, { sku: 'A-100' });
// { success: true, result: 'In stock: 14 units', statusCode: 200, durationMs: 184 }

Calls your real endpoint once with args. It is not counted in usage, and is limited to 40 tests per hour per organisation (429).

Errors