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

# Public API overview

> The Keebai public API — REST + JSON, versioned at /v1, authenticated with Personal Access Tokens, with signed outbound webhooks and an OpenAPI 3 spec.

The Keebai public API connects your CRM, your own backend, automations (Zapier, n8n, Make), or any internal tool to your WhatsApp channels and assistants. Direct, scriptable access — no portal required.

## What you get

<CardGroup cols={2}>
  <Card title="REST + JSON" icon="code">
    Every endpoint accepts and returns JSON. Versioned under `/v1/`, no silent breaking changes.
  </Card>

  <Card title="Personal Access Tokens" icon="key">
    Each user in your tenant can mint their own tokens with scoped permissions and instant revocation.
  </Card>

  <Card title="Granular scopes" icon="shield">
    Permissions split by messages, templates, channels, and webhooks. Grant only what each integration needs.
  </Card>

  <Card title="Signed webhooks" icon="bell">
    Events delivered to your URL with HMAC-SHA256, exponential retries, and `event_id` deduplication.
  </Card>

  <Card title="OpenAPI 3" icon="file-code">
    Auto-generated spec at [api.keebai.com/v1/docs-json](https://api.keebai.com/v1/docs-json). Importable into Postman, Insomnia, or any SDK generator.
  </Card>

  <Card title="Official CLI" icon="terminal">
    `keebai` (npm: `@keebai/cli`) covers login, channel connect, token management, and messaging — all from your shell.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/dev/sdks/typescript">
    `@keebai/sdk` — typed client with full WhatsApp coverage: text, media, interactive, templates, broadcasts.
  </Card>

  <Card title="Agent Skills" icon="robot" href="/dev/sdks/agent-skills">
    Skills for Claude Code, Cursor, Codex, and other AI agents. Your agent sends WhatsApp without you teaching it the SDK.
  </Card>
</CardGroup>

## Base URL

```
https://api.keebai.com/v1
```

All public-API routes live under this prefix. The browsable Swagger UI is at [api.keebai.com/v1/docs](https://api.keebai.com/v1/docs).

## Endpoints

### Session

| Method   | Path           | Scope | Description                                    |
| -------- | -------------- | ----- | ---------------------------------------------- |
| `GET`    | `/v1/me`       | —     | Info about the active token and its scopes.    |
| `DELETE` | `/v1/me/token` | —     | Revoke the current token (server-side logout). |

### Messages

| Method | Path                             | Scope           | Description                                       |
| ------ | -------------------------------- | --------------- | ------------------------------------------------- |
| `POST` | `/v1/messages`                   | `messages:send` | Send any message type on any connected channel.   |
| `POST` | `/v1/flows`                      | `flows:write`   | Create a WhatsApp Flow.                           |
| `POST` | `/v1/messages/bulk`              | `messages:bulk` | Send a template to many recipients (up to 5,000). |
| `GET`  | `/v1/messages/bulk/:broadcastId` | `messages:bulk` | Status of a bulk send.                            |

### Templates

| Method  | Path                | Scope              | Description                                        |
| ------- | ------------------- | ------------------ | -------------------------------------------------- |
| `GET`   | `/v1/templates`     | `templates:read`   | List approved templates for your company.          |
| `POST`  | `/v1/templates`     | `templates:create` | Create and submit a template to Meta for approval. |
| `PATCH` | `/v1/templates/:id` | `templates:update` | Update components, category, language, or status.  |

### Channels

| Method | Path                                       | Scope              | Description                                                                        |
| ------ | ------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------- |
| `GET`  | `/v1/channels`                             | `channels:read`    | [List channels](/dev/endpoints/channels-list), filterable by `type`.               |
| `GET`  | `/v1/channels/:id`                         | `channels:read`    | Get a single channel.                                                              |
| `GET`  | `/v1/whatsapp/numbers`                     | `channels:read`    | [Direct view](/dev/endpoints/whatsapp-numbers) of active `phone_number_id` values. |
| `POST` | `/v1/channels/whatsapp/connect`            | `channels:connect` | [Start a WhatsApp connection](/dev/endpoints/channels-whatsapp-connect).           |
| `GET`  | `/v1/channels/whatsapp/connect/:sessionId` | `channels:connect` | Poll the connect session status.                                                   |

### Outbound webhooks

| Method   | Path                             | Scope             | Description                                     |
| -------- | -------------------------------- | ----------------- | ----------------------------------------------- |
| `POST`   | `/v1/webhooks`                   | `webhooks:manage` | Create a subscription. Returns the secret once. |
| `GET`    | `/v1/webhooks`                   | `webhooks:read`   | List subscriptions.                             |
| `GET`    | `/v1/webhooks/:id`               | `webhooks:read`   | Get a single subscription.                      |
| `PATCH`  | `/v1/webhooks/:id`               | `webhooks:manage` | Update URL, events, headers, or `is_active`.    |
| `POST`   | `/v1/webhooks/:id/rotate-secret` | `webhooks:manage` | Rotate the signing secret.                      |
| `DELETE` | `/v1/webhooks/:id`               | `webhooks:manage` | Delete a subscription.                          |
| `POST`   | `/v1/webhooks/:id/test`          | `webhooks:manage` | Fire a synthetic test event.                    |
| `GET`    | `/v1/webhooks/:id/deliveries`    | `webhooks:read`   | Delivery history.                               |

Full details in [Webhooks → Overview](/dev/webhooks/overview).

### CRM

| Method   | Path                        | Scope                  | Description                                                                              |
| -------- | --------------------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
| `GET`    | `/v1/crm/customers`         | `crm:customers:read`   | [List customers](/dev/endpoints/crm-customers-list) with search and phone lookup.        |
| `GET`    | `/v1/crm/customers/:id`     | `crm:customers:read`   | Get a single customer.                                                                   |
| `POST`   | `/v1/crm/customers`         | `crm:customers:write`  | [Create a customer](/dev/endpoints/crm-customer-create).                                 |
| `PATCH`  | `/v1/crm/customers/:id`     | `crm:customers:write`  | Partially update a customer.                                                             |
| `DELETE` | `/v1/crm/customers/:id`     | `crm:customers:delete` | Delete a customer.                                                                       |
| `GET`    | `/v1/crm/tickets`           | `crm:tickets:read`     | [List tickets](/dev/endpoints/crm-tickets-list) by pipeline, stage, owner, tag, or date. |
| `GET`    | `/v1/crm/tickets/:id`       | `crm:tickets:read`     | Get a single ticket.                                                                     |
| `POST`   | `/v1/crm/tickets`           | `crm:tickets:write`    | [Open a ticket](/dev/endpoints/crm-ticket-create) for a contact.                         |
| `PATCH`  | `/v1/crm/tickets/:id`       | `crm:tickets:write`    | Update, close, reassign, or retag a ticket.                                              |
| `POST`   | `/v1/crm/tickets/:id/stage` | `crm:tickets:write`    | [Move a ticket](/dev/endpoints/crm-ticket-stage) to another pipeline stage.              |
| `DELETE` | `/v1/crm/tickets/:id`       | `crm:tickets:delete`   | Delete a ticket.                                                                         |
| `GET`    | `/v1/crm/tasks`             | `crm:tasks:read`       | [List tasks](/dev/endpoints/crm-tasks-list), filterable by status.                       |
| `GET`    | `/v1/crm/tasks/:id`         | `crm:tasks:read`       | Get a single task.                                                                       |
| `POST`   | `/v1/crm/tasks`             | `crm:tasks:write`      | [Create a task](/dev/endpoints/crm-task-create).                                         |
| `PATCH`  | `/v1/crm/tasks/:id`         | `crm:tasks:write`      | Update a task's status, assignee, or due date.                                           |
| `DELETE` | `/v1/crm/tasks/:id`         | `crm:tasks:delete`     | Delete a task.                                                                           |
| `GET`    | `/v1/crm/notes`             | `crm:notes:read`       | [List notes](/dev/endpoints/crm-notes-list) by contact, ticket, or type.                 |
| `GET`    | `/v1/crm/notes/:id`         | `crm:notes:read`       | Get a single note.                                                                       |
| `POST`   | `/v1/crm/notes`             | `crm:notes:write`      | [Log a note](/dev/endpoints/crm-note-create), call, email, or meeting.                   |
| `PATCH`  | `/v1/crm/notes/:id`         | `crm:notes:write`      | Edit a note's text or type.                                                              |
| `DELETE` | `/v1/crm/notes/:id`         | `crm:notes:delete`     | Delete a note.                                                                           |

Full details in [CRM → Overview](/dev/crm/overview). Note that CRM reads span the whole company while writes stay scoped to the token's project.

### Loyalty

| Method | Path                                               | Scope           | Description                                                                                  |
| ------ | -------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/loyalty/programs`                             | `loyalty:read`  | [List programs](/dev/endpoints/loyalty-programs-list) — points, stamps, or tiers.            |
| `GET`  | `/v1/loyalty/programs/:id`                         | `loyalty:read`  | Get a program with its rules.                                                                |
| `GET`  | `/v1/loyalty/templates`                            | `loyalty:read`  | [List a program's wallet card designs](/dev/endpoints/loyalty-templates-list).               |
| `GET`  | `/v1/loyalty/templates/:id`                        | `loyalty:read`  | Get a single template.                                                                       |
| `GET`  | `/v1/loyalty/memberships`                          | `loyalty:read`  | [Find a membership](/dev/endpoints/loyalty-memberships-list) by customer, phone, or program. |
| `GET`  | `/v1/loyalty/memberships/:id`                      | `loyalty:read`  | Get a membership with its balance.                                                           |
| `POST` | `/v1/loyalty/memberships`                          | `loyalty:write` | [Enroll a customer](/dev/endpoints/loyalty-membership-enroll).                               |
| `GET`  | `/v1/loyalty/memberships/:id/ledger`               | `loyalty:read`  | [Movement history](/dev/endpoints/loyalty-ledger-list).                                      |
| `POST` | `/v1/loyalty/memberships/:id/ledger`               | `loyalty:write` | [Accrue, redeem, or correct](/dev/endpoints/loyalty-ledger-record).                          |
| `POST` | `/v1/loyalty/memberships/:id/passes/google`        | `loyalty:write` | [Issue the Google Wallet pass](/dev/endpoints/loyalty-pass-google).                          |
| `POST` | `/v1/loyalty/memberships/:id/passes/apple/link`    | `loyalty:write` | [Issue the Apple Wallet link](/dev/endpoints/loyalty-pass-apple-link).                       |
| `POST` | `/v1/loyalty/memberships/:id/passes/notify`        | `loyalty:write` | [Push a message to the card](/dev/endpoints/loyalty-pass-notify).                            |
| `GET`  | `/v1/loyalty/memberships/:id/passes/notifications` | `loyalty:read`  | [Message history](/dev/endpoints/loyalty-pass-notifications).                                |

Full details in [Loyalty → Overview](/dev/loyalty/overview). Programs and card designs are authored in the portal; the API covers enrollment, balances, and passes.

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/dev/quickstart">
    From zero to first message in five minutes.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/dev/sdks/typescript">
    Typed client for Node, edge runtimes, and browsers.
  </Card>

  <Card title="CLI" icon="terminal" href="/dev/sdks/cli">
    Login, connect WhatsApp, and send messages from your terminal.
  </Card>

  <Card title="Agent Skills" icon="robot" href="/dev/sdks/agent-skills">
    Skills for Claude Code, Cursor, Codex, and other AI agents.
  </Card>

  <Card title="API keys" icon="key" href="/dev/api-keys">
    How to create, list, and revoke tokens.
  </Card>

  <Card title="Authentication" icon="lock" href="/dev/authentication">
    How to send the token on every request and handle auth errors.
  </Card>

  <Card title="Outbound webhooks" icon="bell" href="/dev/webhooks/overview">
    Receive signed events at your endpoint.
  </Card>

  <Card title="Connect WhatsApp" icon="plug" href="/dev/endpoints/channels-whatsapp-connect">
    Onboard a new WhatsApp Business channel without the portal.
  </Card>

  <Card title="CRM" icon="address-book" href="/dev/crm/overview">
    Customers, tickets, tasks, and notes over REST.
  </Card>

  <Card title="Ecommerce" icon="cart-shopping" href="/dev/ecommerce/overview">
    Read the catalog, carts, and sales, and get a webhook when a sale closes.
  </Card>

  <Card title="Loyalty" icon="wallet" href="/dev/loyalty/overview">
    Points, stamps, and tiers, with the card in Apple Wallet or Google Wallet.
  </Card>

  <Card title="Assistants" icon="robot" href="/dev/assistants/overview">
    Create assistants, write the blocks that make up their prompt, and give them webhooks to call.
  </Card>

  <Card title="MCP server" icon="plug-circle-bolt" href="/dev/mcp/overview">
    Give an AI agent the same API as 101 tools, with the same token and scopes.
  </Card>
</CardGroup>

## Is something broken?

Live availability per component, plus current and past incidents, is at **[status.keebai.com](https://status.keebai.com)**. It is served independently of the API, so it stays up when we do not.

Check it before opening a ticket — if the component you are calling is already reported degraded, we are on it.

## Roadmap

Planned, no firm dates:

* **Smart templates** — map unstructured data into template variables with an LLM.
* **Scheduled messages** — schedule and cancel future sends.
* **Tickets** — open and update tickets from the API.
* **More webhook events** — `conversation.created`, `conversation.escalated_to_human`, `instagram.message.received`.

Need one of these sooner? Write us at [support@keebai.com](mailto:support@keebai.com).