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

# API Reference

> REST API for contacts, conversations, messages, and media. Bearer token authentication.

# API Reference

Kaanha AI provides a REST API for programmatic access to contacts, conversations, messages, and more. All API endpoints use **Bearer token authentication** via API Keys.

## Authentication

### Create an API Key

1. Go to **Settings → API Keys → Create Key**
2. Give it a descriptive name and optional expiry date
3. Copy the key immediately — it won't be shown again

### Using the API Key

Include the key in all requests:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

***

## Base URL

```
https://app.kaanha.ai/api/whatsapp-api
```

***

## Endpoints

### Status

**GET** `/api/whatsapp-api/status`

Returns WhatsApp connection status for the authenticated organization.

```json theme={null}
{
  "connected": true,
  "phoneNumber": "+91 98765 43210",
  "connectionType": "cloud_api",
  "businessName": "Acme Corp"
}
```

***

### Contacts

**GET** `/api/whatsapp-api/contacts`

List contacts with optional filtering.

| Query Param | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `search`    | string | Search by name or phone                  |
| `tag`       | string | Filter by tag                            |
| `page`      | number | Page number (default: 1)                 |
| `limit`     | number | Results per page (default: 20, max: 100) |

**POST** `/api/whatsapp-api/contacts`

Create a new contact.

```json theme={null}
{
  "phone": "+919876543210",
  "name": "John Doe",
  "email": "john@example.com",
  "tags": ["vip", "retail"],
  "optedIn": true
}
```

***

### Conversations

**GET** `/api/whatsapp-api/chats`

List conversations.

| Query Param | Type   | Description                |
| ----------- | ------ | -------------------------- |
| `status`    | string | OPEN / ASSIGNED / RESOLVED |
| `page`      | number | Page number                |

**GET** `/api/whatsapp-api/chats/{conversationId}`

Get a single conversation with recent messages.

***

### Messages

**GET** `/api/whatsapp-api/messages`

List recent messages across all conversations.

**POST** `/api/whatsapp-api/send`

Send a message to a contact.

```json theme={null}
{
  "to": "+919876543210",
  "type": "text",
  "text": "Hello! How can I help you today?"
}
```

**Supported message types:**

| Type          | Required Fields                          |
| ------------- | ---------------------------------------- |
| `text`        | `text`                                   |
| `image`       | `mediaUrl` or `mediaId`                  |
| `document`    | `mediaUrl`, `filename`                   |
| `audio`       | `mediaUrl`                               |
| `video`       | `mediaUrl`                               |
| `template`    | `templateName`, `language`, `components` |
| `interactive` | `interactive` (button/list format)       |
| `location`    | `latitude`, `longitude`, `name`          |
| `contact`     | `contacts` array                         |
| `reaction`    | `messageId`, `emoji`                     |

***

### Media

**POST** `/api/whatsapp-api/media`

Upload media. Returns a `mediaId` for use in message sends.

```
Content-Type: multipart/form-data
Body: file (max 16MB)
```

Supported types: images (JPEG, PNG, WebP), documents (PDF, DOCX), audio (MP3, OGG), video (MP4)

**GET** `/api/media/{mediaId}`

Download/stream a media file by ID.

***

## MCP Server (Claude / AI Assistants)

Kaanha AI exposes an MCP (Model Context Protocol) server for integration with Claude and other AI assistants.

### stdio Transport (Claude Desktop / Claude Code)

```bash theme={null}
# Register with Claude (from your local clone of the platform)
claude mcp add wasender -- node src/mcp/server.mjs
```

Available tools: `list_contacts`, `get_contact`, `create_contact`, `list_conversations`, `get_conversation`, `send_message`, `list_templates`, `send_broadcast`, `get_analytics`, `list_ai_agents`, `list_quick_replies`, `create_payment_link`

### SSE Transport (Network Clients)

```
GET https://app.kaanha.ai/api/mcp/sse
Authorization: Bearer YOUR_API_KEY
```

***

## Rate Limits

| Scope         | Limit                                                 |
| ------------- | ----------------------------------------------------- |
| API requests  | 120 requests/minute per IP                            |
| Message sends | 20 messages/hour per recipient                        |
| Broadcast     | 1,000 contacts/broadcast on Starter; unlimited on Pro |
| File uploads  | 16MB max per file                                     |

Rate limit responses return HTTP `429` with a `Retry-After` header.

***

## Webhooks (Outgoing)

Kaanha AI can push events to your server. See [Webhooks Guide](./webhooks.md).

***

## Error Codes

| HTTP Status | Meaning                                 |
| ----------- | --------------------------------------- |
| `200`       | Success                                 |
| `201`       | Created                                 |
| `400`       | Bad request (missing or invalid fields) |
| `401`       | Unauthorized (missing/expired API key)  |
| `403`       | Forbidden (insufficient permissions)    |
| `404`       | Not found                               |
| `409`       | Conflict (duplicate resource)           |
| `429`       | Rate limit exceeded                     |
| `500`       | Server error                            |

Error responses always include a JSON body:

```json theme={null}
{
  "error": "Human-readable error message"
}
```