> ## Documentation Index
> Fetch the complete documentation index at: https://doc.convo.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Convo REST API Reference: Overview and Auth Guide

> Complete reference for the Convo REST API. Base URL, authentication headers, response formats, error codes, and pagination explained.

The Convo REST API allows you to manage WhatsApp messaging, contacts, campaigns, templates, webhooks, and catalogues programmatically. All endpoints are served over HTTPS and return JSON responses.

***

## Base URL

Every API request is made against the following base URL:

```text theme={null}
https://connect.api-wa.co/project-apis/v1/
```

***

## Authentication

Convo uses a single authentication header. Include the `X-API-WA-Project-API-Pwd` header on every request:

| Header                     | Description                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------- |
| `X-API-WA-Project-API-Pwd` | **Project API Password**. Tied to a specific project and used for all API requests. |

<Note>
  You can find your **Project API Password** in your Convo dashboard under **Settings → Developers → API Keys**.
</Note>

***

## Request Format

All request bodies must be sent as JSON. Set the `Content-Type` header accordingly:

```text theme={null}
Content-Type: application/json
```

**Example request with body:**

```bash theme={null}
curl -X POST https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/messages \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"to": "919876543210", "type": "text", "messaging_product": "whatsapp", "text": {"body": "Hello!"}}'
```

***

## Response Format

All responses are returned as JSON objects.

### Success response

A successful request returns an HTTP `2xx` status code along with a JSON payload. The exact shape varies by endpoint; below is a representative example:

```json theme={null}
{
  "id": "61f0624bcf0a58553378ceb4",
  "active": true,
  "display_name": "Shop XY",
  "email": "owner@example.com",
  "company": "Shop XY",
  "timezone": "Asia/Calcutta"
}
```

### Error response

When a request fails, the API returns a non-`2xx` status code and a JSON body in the following shape:

```json theme={null}
{
  "name": "ERR400",
  "message": "Invalid Business ID!"
}
```

***

## Error Codes

| HTTP Status | Error Name | Meaning                                                                                            |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------- |
| `400`       | `ERR400`   | **Bad Request** — one or more required parameters are missing or have invalid values.              |
| `401`       | `ERR401`   | **Unauthorized** — the API key is missing, expired, or does not have permission for this resource. |
| `404`       | `ERR404`   | **Not Found** — the requested resource does not exist.                                             |
| `409`       | `ERR409`   | **Conflict** — the resource you are trying to create already exists.                               |
| `500`       | `ERR500`   | **Internal Server Error** — something went wrong on Convo's end. Retry with exponential back-off.  |

All error responses follow the same envelope:

```json theme={null}
{
  "name": "ERR4xx",
  "message": "A human-readable description of the error."
}
```

***

## Pagination

Convo endpoints use two pagination styles depending on the resource.

### Cursor-based pagination

List endpoints that return large, time-ordered datasets (for example, messages and contacts) use **cursor pagination**. Pass the opaque cursor string returned in the previous response as the `before` or `after` query parameter to page backwards or forwards through results.

```text theme={null}
GET /messages?after=<cursor>&limit=50
```

| Parameter | Type    | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| `after`   | string  | Return records **after** this cursor (next page).      |
| `before`  | string  | Return records **before** this cursor (previous page). |
| `limit`   | integer | Maximum number of records to return per page.          |

The response includes a `paging` object:

```json theme={null}
{
  "data": [...],
  "paging": {
    "cursors": {
      "before": "abc123",
      "after":  "xyz789"
    },
    "next": "/messages?after=xyz789&limit=50"
  }
}
```

### Offset-based pagination

Some endpoints (for example, campaign lists) use `limit` and `skip` query parameters:

```text theme={null}
GET /campaigns?limit=20&skip=40
```

| Parameter | Type    | Description                                         |
| --------- | ------- | --------------------------------------------------- |
| `limit`   | integer | Maximum number of records to return.                |
| `skip`    | integer | Number of records to skip before returning results. |

***

## Resource Overview

<CardGroup cols={2}>
  <Card title="Messages" icon="message" href="/api-reference/messages/send-message">
    Send template messages, session messages, and media to WhatsApp contacts.
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts/create-contact">
    Create, retrieve, update, and manage your WhatsApp contact list.
  </Card>

  <Card title="Templates" icon="file-lines" href="/api-reference/templates/list-templates">
    Fetch approved WhatsApp message templates associated with your project.
  </Card>

  <Card title="Campaigns" icon="bullhorn" href="/api-reference/campaigns/list-campaigns">
    Schedule and manage broadcast campaigns to segmented contact lists.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/api-reference/webhooks/list-webhooks">
    Register webhook URLs to receive real-time delivery and reply events.
  </Card>

  <Card title="Catalogue" icon="shop" href="/api-reference/catalogue/get-catalogue">
    Manage your WhatsApp product catalogue and inventory listings.
  </Card>

  <Card title="Business" icon="building" href="/api-reference/business/get-business">
    Retrieve business account details, linked projects, and billing info.
  </Card>

  <Card title="Project" icon="folder-open" href="/api-reference/project/get-project">
    Fetch project-level details including WhatsApp number, plan, and MAU usage.
  </Card>
</CardGroup>