Integrations API

This page documents the server-to-server API that enables external platforms and products, such as CRMs, to integrate with a Kakapo bot. For example, a CRM can use the API to generate a reply to a customer email based on the company’s knowledge base.

Authentication

Requests use a bot-scoped API key created from the bot's dashboard settings:

Authorization: Bearer kakapo_live_<prefix>_<secret>

The full key is shown once at creation time and stored by Kakapo only as a hash. Keys are scoped to a single bot, carry explicit scopes, and can be revoked at any time from the dashboard.

Common response envelope

Successful responses return:

{
  "ok": true,
  "data": {}
}

Errors return:

{
  "ok": false,
  "error": {
    "message": "Error message",
    "details": null
  }
}

POST /api/integrations/v1/bots/{botId}/reply-draft

Composes a grounded reply draft for a message or email thread. Kakapo only generates the suggested reply text; your application is responsible for reviewing it, sending it, and managing the conversation.

• Auth: Bot API key bearer token.
• Rate limit: current plan per-minute limit, keyed by API key and caller IP.
• Retrieval scope: always filtered by bot_id.
• Authorization boundary: the route botId and bot-scoped API key. The metadata fields (caller, crm_workspace_id, crm_thread_id, request_id) are optional audit context only and do not authorize access.

Request body:

{
  "thread": {
    "channel": "email",
    "subject": "Question about pricing",
    "messages": [
      {
        "role": "customer",
        "from": "customer@example.com",
        "sent_at": "2026-07-04T10:00:00Z",
        "text": "Do you support annual billing?"
      }
    ]
  },
  "reply_context": {
    "tone": "professional",
    "locale": "en",
    "goal": "answer_customer"
  },
  "metadata": {
    "caller": "acme-crm",
    "crm_workspace_id": "workspace_123",
    "crm_thread_id": "thread_456",
    "request_id": "request_789"
  }
}

Response data:

{
  "reply": {
    "text": "Yes, we support annual billing...",
    "confidence": 0.82
  },
  "grounding": [
    {
      "source_id": "uuid",
      "title": "Pricing FAQ",
      "type": "qa",
      "url": null
    }
  ],
  "usage": {
    "model": "gpt-4o-mini",
    "tokens": 1234
  },
  "failure_reason": null
}

Safe failure example:

{
  "reply": {
    "text": "",
    "confidence": 0
  },
  "grounding": [],
  "usage": {
    "model": "gpt-4o-mini",
    "tokens": 0
  },
  "failure_reason": "no_relevant_context"
}

Versioning

This API is versioned in the URL, currently /v1/. Integrations built against /v1/ will keep working unchanged; any breaking change will ship under a new version segment (e.g. /v2/) rather than altering /v1/ behavior.