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

# Pilot Status API Overview

> Base URL, x-api-key authentication, key scopes, and common HTTP errors for the Pilot Status WhatsApp API.

# Pilot Status API Overview

Pilot Status is a platform for sending WhatsApp messages (transactional and marketing/bulk) with template control, versioning, and operational visibility via dashboard, API, and webhooks.

## Base URL

```text theme={null}
https://pilotstatus.com.br/v1
```

## Authentication

Every request requires an API key sent in the `x-api-key` header (or `x-api-key-id` with the key ID). Keys use the `ps_` prefix.

<Warning>
  The API does **not** use `Authorization: Bearer` tokens. Always authenticate with the `x-api-key: ps_...` header (or `x-api-key-id`).
</Warning>

```bash theme={null}
curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key: ps_your_key_here"
```

### Key scopes

| Scope                         | Bound to               | Can call                                                                                                                                      |
| ----------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Number-scoped** (default)   | One WhatsApp number    | All action/data endpoints for that number: `POST /v1/messages/send`, message status, cancel, groups, newsletters, templates, analytics, media |
| **Tenant-scoped** (singleton) | The tenant (no number) | Only number lifecycle management: `/v1/numbers/*` and `/v1/remote-pairing/*`                                                                  |

See [API Authentication](/api/authentication) for details.

## Core concepts

* **Template**: a versioned message model referenced by `templateId` on API sends. For **Meta** numbers, templates are submitted to Meta for approval; for **non-official WhatsApp API (Evolution)** numbers, they are created locally without an approval step.
* **Message**: a send attempt created by `POST /v1/messages/send`.
* **Webhooks**: delivery events (sent/delivered/read/failed) and inbound messages (reply/received/group).
* **Read receipts**: `READ` status, `readAt`, and the `message.read` webhook only occur when the recipient contact has WhatsApp read receipts enabled.

## Typical integration flow

<Steps>
  <Step title="Create templates">
    Create templates in the dashboard (`/templates`).
  </Step>

  <Step title="Connect WhatsApp">
    Configure your WhatsApp number/instance in the dashboard (`/profile` and `/numbers`).
  </Step>

  <Step title="Create an API key">
    Create an API key on the `/api-keys` page.
  </Step>

  <Step title="Send messages">
    Send messages with [`POST /v1/messages/send`](/api/messages/send).
  </Step>

  <Step title="Track delivery">
    Query status with [`GET /v1/messages/{messageId}`](/api/messages/status) and/or consume events via webhooks.
  </Step>
</Steps>

## Common HTTP errors

| Status | Meaning                                                              |
| ------ | -------------------------------------------------------------------- |
| `400`  | Invalid payload (e.g., phone not in E.164, missing required fields)  |
| `401`  | Missing or invalid `x-api-key` / `x-api-key-id` header               |
| `402`  | Paid subscription required (e.g., `SUBSCRIPTION_REQUIRED_FOR_MEDIA`) |
| `403`  | Valid key, but operation blocked (e.g., wrong key scope)             |
| `404`  | Resource not found within the key's scope                            |
| `429`  | Rate limit exceeded                                                  |

## Warnings (WhatsApp / anti-spam)

<Warning>
  High-volume and unsolicited sending can trigger WhatsApp anti-spam mechanisms (rate limits, blocks, and bans). You are responsible for opt-in/consent and compliance with applicable laws and WhatsApp policies.
</Warning>