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

# Waply REST API: base URL, errors, and rate limits

> Start building with the Waply REST API. Covers the base URL, JSON request and response format, error codes, and per-plan rate limits for Growth and Enterprise.

The Waply REST API gives you programmatic access to contacts, conversations, messages, broadcasts, and webhooks on your Waply account. API access is available on the **Growth** and **Enterprise** plans. If you are on the Starter plan, upgrade from the Billing page in your dashboard to get started.

## Base URL

All API requests are made to the following base URL:

```
https://api.waply.io/v1
```

Every endpoint path in this reference is relative to this base URL. For example, `GET /contacts` maps to `https://api.waply.io/v1/contacts`.

## What you can do with the API

The Waply API covers the core objects and workflows in the platform:

<CardGroup cols={2}>
  <Card title="Contacts" icon="address-book" href="/api-reference/contacts">
    Create, retrieve, update, and delete contacts. Filter by tag, lifecycle stage, or search term.
  </Card>

  <Card title="Conversations" icon="messages" href="/api-reference/conversations">
    List and read conversations, assign them to agents or teams, resolve them, and add internal notes.
  </Card>

  <Card title="Messages" icon="paper-plane" href="/api-reference/messages">
    Send text, template, image, and document messages to contacts across WhatsApp and other channels.
  </Card>

  <Card title="Broadcasts" icon="bullhorn" href="/api-reference/broadcasts">
    Send bulk messages to segmented audiences. Schedule broadcasts or send them immediately.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Register HTTPS endpoints to receive real-time events for messages, conversations, contacts, and broadcasts.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Authenticate every request with a Bearer token from your Waply API keys.
  </Card>
</CardGroup>

## Request format

Send all request bodies as JSON and include the `Content-Type: application/json` header on requests that have a body.

```bash theme={null}
curl --request POST \
  --url https://api.waply.io/v1/contacts \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"phone": "+14155552671", "name": "Jane Doe"}'
```

## Response format

All responses are JSON. Successful responses return an HTTP `2xx` status code. Collection endpoints return a `data` array along with pagination metadata.

```json theme={null}
{
  "data": [...],
  "total": 142,
  "page": 1
}
```

Single-resource endpoints return the object directly:

```json theme={null}
{
  "id": "con_01HXYZ",
  "phone": "+14155552671",
  "name": "Jane Doe"
}
```

## Error format

When a request fails, Waply returns a non-`2xx` status code and a JSON body with an `error` object:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The 'phone' field must be in E.164 format."
  }
}
```

### Common error codes

| HTTP status | Meaning                                                                 |
| ----------- | ----------------------------------------------------------------------- |
| `401`       | Invalid or missing API key. Check your `Authorization` header.          |
| `403`       | Your plan does not include API access. Upgrade to Growth or Enterprise. |
| `404`       | The requested resource does not exist.                                  |
| `422`       | Validation error. Check the `message` field for details.                |
| `429`       | Rate limit exceeded. Slow down your requests.                           |

## Rate limits

Rate limits are enforced per API key on a rolling 60-second window.

| Plan       | Requests per minute |
| ---------- | ------------------- |
| Growth     | 100                 |
| Enterprise | 500                 |

When you exceed your limit, the API returns a `429` status. The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

<Tip>
  If you are running into rate limits on Growth, consider batching operations or using broadcasts for bulk messaging rather than sending individual messages in a loop.
</Tip>

## Next steps

Authenticate your first request by following the [Authentication guide](/api-reference/authentication).