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

# API reference

> Base URL, authentication, rate limiting, response format, and complete MsgFlash public API surface.

## Base URL

```txt theme={null}
https://srv.msgflash.com
```

All public endpoints are prefixed with `/api/v1/`.

Examples:

```txt theme={null}
https://srv.msgflash.com/api/v1/messages/send
https://srv.msgflash.com/api/v1/templates
https://srv.msgflash.com/api/v1/contacts
https://srv.msgflash.com/api/v1/billing/usage
```

***

## Authentication

All requests to `/api/v1/*` require a MsgFlash API key in the `x-api-key` header.

```bash theme={null}
curl https://srv.msgflash.com/api/v1/usage \
  -H "x-api-key: msgf_live_your_api_key_here"
```

See [Authentication](/authentication) for exact header format and security requirements.

### Team workspace (`msgf_team_…`)

Team API keys require **`X-Team-Id`** matching the key’s team; workspace **`/api/v1/*`** routes then use the team’s shared data and the team owner’s plan. Personal keys must not send `X-Team-Id` (`TEAM_KEY_REQUIRED`). Account, compact usage, and most billing reads require a personal key (`TEAM_KEY_NOT_ALLOWED` with a team key). Full rules: [Team context](/api-reference/teams/team-context).

***

## Rate limiting

| Limit               | Value                     |
| ------------------- | ------------------------- |
| Requests per second | 10 req/s                  |
| Scope               | Per API key               |
| Error code          | `API_RATE_LIMIT_EXCEEDED` |

If the limit is exceeded:

```json theme={null}
{
  "error": {
    "code": "API_RATE_LIMIT_EXCEEDED",
    "message": "Too many API requests"
  }
}
```

<Note>
  The real-time rate limit is separate from the monthly `monthlyApiRequestQuota`. You can stay under your monthly quota and still receive `429` if you exceed 10 req/s.
</Note>

***

## Response format

### Success

All successful responses are wrapped in `data`.

```json theme={null}
{
  "data": {
    "id": "uuid",
    "status": "queued"
  }
}
```

For simple lists:

```json theme={null}
{
  "data": [
    { "id": "..." },
    { "id": "..." }
  ]
}
```

For paginated lists:

```json theme={null}
{
  "data": {
    "messages": [],
    "nextCursor": null,
    "hasMore": false
  }
}
```

### Error

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Message not found"
  }
}
```

See [Error codes](/resources/error-codes) for the main codes.

***

## Available endpoints

### Messages

| Method | Endpoint                    | Description             |
| ------ | --------------------------- | ----------------------- |
| `POST` | `/api/v1/messages/send`     | Send an instant message |
| `POST` | `/api/v1/messages/schedule` | Schedule a message      |
| `GET`  | `/api/v1/messages`          | List messages           |
| `GET`  | `/api/v1/messages/{id}`     | Message details         |

### Campaigns

| Method | Endpoint                        | Description         |
| ------ | ------------------------------- | ------------------- |
| `POST` | `/api/v1/campaigns`             | Create a campaign   |
| `GET`  | `/api/v1/campaigns/{id}`        | Campaign details    |
| `GET`  | `/api/v1/campaigns/{id}/stats`  | Delivery statistics |
| `POST` | `/api/v1/campaigns/{id}/pause`  | Pause a campaign    |
| `POST` | `/api/v1/campaigns/{id}/resume` | Resume a campaign   |

### Templates

| Method   | Endpoint                         | Description               |
| -------- | -------------------------------- | ------------------------- |
| `GET`    | `/api/v1/templates`              | List templates            |
| `POST`   | `/api/v1/templates`              | Create a template         |
| `GET`    | `/api/v1/templates/{id}`         | Template details          |
| `PUT`    | `/api/v1/templates/{id}`         | Update a template         |
| `DELETE` | `/api/v1/templates/{id}`         | Delete a template         |
| `POST`   | `/api/v1/templates/{id}/preview` | Preview a template render |

### Contacts

| Method   | Endpoint                                      | Description            |
| -------- | --------------------------------------------- | ---------------------- |
| `GET`    | `/api/v1/contacts`                            | List contacts          |
| `POST`   | `/api/v1/contacts`                            | Create a contact       |
| `GET`    | `/api/v1/contacts/{id}`                       | Contact details        |
| `PUT`    | `/api/v1/contacts/{id}`                       | Update a contact       |
| `DELETE` | `/api/v1/contacts/{id}`                       | Delete a contact       |
| `POST`   | `/api/v1/contacts/bulk-delete`                | Bulk delete contacts   |
| `GET`    | `/api/v1/contacts/bulk-jobs`                  | List bulk contact jobs |
| `GET`    | `/api/v1/contacts/bulk-jobs/{jobId}`          | Bulk job details       |
| `GET`    | `/api/v1/contacts/bulk-jobs/{jobId}/progress` | Bulk job progress      |
| `POST`   | `/api/v1/contacts/bulk-jobs/{jobId}/cancel`   | Cancel a bulk job      |

### Contact groups

| Method   | Endpoint                                    | Description               |
| -------- | ------------------------------------------- | ------------------------- |
| `GET`    | `/api/v1/contacts/groups`                   | List groups               |
| `POST`   | `/api/v1/contacts/groups`                   | Create a group            |
| `GET`    | `/api/v1/contacts/groups/{groupId}`         | Group details             |
| `PUT`    | `/api/v1/contacts/groups/{groupId}`         | Update a group            |
| `DELETE` | `/api/v1/contacts/groups/{groupId}`         | Delete a group            |
| `POST`   | `/api/v1/contacts/groups/{groupId}/members` | Add members               |
| `DELETE` | `/api/v1/contacts/groups/{groupId}/members` | Remove members            |
| `GET`    | `/api/v1/contacts/groups/{groupId}/members` | List members              |
| `GET`    | `/api/v1/contacts/{id}/groups`              | List groups for a contact |

### Webhooks

| Method   | Endpoint                | Description                 |
| -------- | ----------------------- | --------------------------- |
| `GET`    | `/api/v1/webhooks`      | List your webhook endpoints |
| `POST`   | `/api/v1/webhooks`      | Create a webhook endpoint   |
| `DELETE` | `/api/v1/webhooks/{id}` | Delete a webhook endpoint   |

### WhatsApp statuses

| Method | Endpoint           | Description               |
| ------ | ------------------ | ------------------------- |
| `POST` | `/api/v1/statuses` | Publish a WhatsApp status |

### Instances

| Method | Endpoint                       | Description         |
| ------ | ------------------------------ | ------------------- |
| `GET`  | `/api/v1/instances`            | List instances      |
| `GET`  | `/api/v1/instances/{id}`       | Instance details    |
| `GET`  | `/api/v1/instances/{id}/state` | Live instance state |

### Billing public read-only

| Method | Endpoint                       | Description                             |
| ------ | ------------------------------ | --------------------------------------- |
| `GET`  | `/api/v1/usage`                | Compact usage summary                   |
| `GET`  | `/api/v1/billing/plans`        | Plan catalog                            |
| `GET`  | `/api/v1/billing/subscription` | Current subscription and billing period |
| `GET`  | `/api/v1/billing/usage`        | Usage, limits, and features             |
| `GET`  | `/api/v1/billing/payments`     | Payment history                         |