# API reference

> Every WhaBuzz endpoint with request and response schemas, errors and code samples in curl, Node, Python and PHP, rendered from the OpenAPI 3.1 contract.

Canonical: https://docs.whabuzz.com/reference/

The HTML page is rendered in the browser by Scalar from the OpenAPI contract. For machines, use:

- [OpenAPI 3.1 (YAML)](https://docs.whabuzz.com/openapi.yaml)
- [OpenAPI 3.1 (JSON)](https://docs.whabuzz.com/openapi.json)
- [Every operation as plain text, plus all guides](https://docs.whabuzz.com/llms-full.txt)
- [API conventions](https://docs.whabuzz.com/conventions.md): base URL, auth, errors, ids, timing

Base URL: `https://api.whabuzz.com`. 75 operations in 14 groups.

## Health

- `GET /v1/health`: Service health

## Tenant

- `GET /v1/tenant`: Current tenant, including the Getting-started checklist
- `PATCH /v1/tenant`: Update retention or billing email

## Tenants

- `GET /v1/tenants`: List tenants created by your app key
- `POST /v1/tenants`: Create a tenant for one of your customers
- `GET /v1/tenants/{tenant_id}`: Get one of your app's tenants

## API keys

- `GET /v1/api-keys`: List API keys (prefix only)
- `POST /v1/api-keys`: Create an API key
- `DELETE /v1/api-keys/{key_id}`: Revoke a key now
- `POST /v1/api-keys/{key_id}/rotate`: Rotate a key

## Numbers

- `GET /v1/numbers`: List numbers
- `GET /v1/numbers/{phone_number_id}`: Get a number
- `POST /v1/numbers/embedded-signup`: Finish Embedded Signup with the code from Meta's popup
- `POST /v1/numbers/connect`: Connect an existing WABA with a business system-user token
- `POST /v1/numbers/migrate`: Start migrating a number into one of your WABAs
- `POST /v1/numbers/{phone_number_id}/register`: Register the number with Cloud API
- `POST /v1/numbers/{phone_number_id}/deregister`: Deregister the number
- `POST /v1/numbers/{phone_number_id}/request-code`: Request an SMS or voice verification code
- `POST /v1/numbers/{phone_number_id}/verify-code`: Verify the code
- `POST /v1/numbers/{phone_number_id}/two-step`: Set or change the two-step verification PIN
- `POST /v1/numbers/{phone_number_id}/subscribe`: Re-subscribe the number's WABA to WhaBuzz (repair)
- `GET /v1/numbers/{phone_number_id}/business-profile`: Get the WhatsApp business profile
- `POST /v1/numbers/{phone_number_id}/business-profile`: Update the WhatsApp business profile

## Connect sessions

- `POST /v1/connect-sessions`: Create a hosted Embedded Signup link
- `GET /v1/connect-sessions/{session_id}`: Get a Connect session

## Messages

- `POST /v1/messages`: Send a message
- `POST /v1/messages/read`: Mark an inbound message read, optionally showing a typing indicator
- `POST /v1/messages/batch`: Send many messages from one number
- `GET /v1/messages/batch/{batch_id}`: Batch progress
- `GET /v1/messages/batch/{batch_id}/items`: Batch items with Meta's response for each
- `POST /v1/messages/batch/{batch_id}/cancel`: Cancel the unsent part of a batch

## Media

- `POST /v1/media`: Upload media to Meta for sending
- `GET /v1/media/{media_id}`: Download inbound media
- `DELETE /v1/media/{media_id}`: Delete uploaded media from Meta

## Templates

- `GET /v1/templates`: List templates
- `POST /v1/templates`: Submit a template to Meta
- `GET /v1/templates/{template_id}`: Get a template
- `POST /v1/templates/{template_id}`: Edit a template
- `DELETE /v1/templates/{template_id}`: Delete a template
- `POST /v1/templates/sync`: Re-read every template from Meta
- `GET /v1/templates/library`: Browse Meta's template library
- `POST /v1/templates/media-handle`: Upload a header sample and get a handle for template creation

## Webhooks

- `GET /v1/webhooks`: List endpoints
- `POST /v1/webhooks`: Add an endpoint
- `GET /v1/webhooks/{endpoint_id}`: Get an endpoint
- `PATCH /v1/webhooks/{endpoint_id}`: Change URL, event types, description or status
- `DELETE /v1/webhooks/{endpoint_id}`: Delete an endpoint
- `POST /v1/webhooks/{endpoint_id}/verify`: Send the verify ping again
- `POST /v1/webhooks/{endpoint_id}/rotate-secret`: Rotate the signing secret
- `POST /v1/webhooks/{endpoint_id}/replay`: Re-send deliveries in a time range
- `GET /v1/webhook-deliveries`: List deliveries
- `GET /v1/webhook-deliveries/{delivery_id}`: Get a delivery with its attempt log
- `POST /v1/webhook-deliveries/{delivery_id}/replay`: Re-send one delivery now

## Events

- `GET /v1/events`: Search the event log
- `GET /v1/events/{event_id}`: Get one event with its full envelope and deliveries

## Billing

- `GET /v1/billing`: Plan, active numbers and next charge
- `POST /v1/billing/mandate`: Set up autopay
- `GET /v1/billing/invoices`: Invoices
- `GET /v1/billing/invoices/{invoice_id}`: Printable invoice (HTML) or JSON with Accept application/json
- `POST /v1/billing/invoices/{invoice_id}/pay`: Pay a failed invoice now

## Admin

- `GET /v1/admin/tenants`: All tenants (approval queue with status=pending_approval)
- `POST /v1/admin/tenants/{tenant_id}/approve`: Approve a tenant
- `POST /v1/admin/tenants/{tenant_id}/reject`: Reject a tenant
- `POST /v1/admin/tenants/{tenant_id}/suspend`: Suspend a tenant
- `POST /v1/admin/tenants/{tenant_id}/reinstate`: Reinstate a suspended tenant
- `GET /v1/admin/numbers`: Every number across tenants
- `GET /v1/admin/health`: Pipeline health
- `GET /v1/admin/audit`: Audit log
- `GET /v1/admin/billing`: Billing across tenants
- `GET /v1/admin/mail/last`: Last email sent to an address (EMAIL_MODE=log only)
- `GET /v1/admin/apps`: Platform apps
- `POST /v1/admin/apps`: Create a platform app
- `POST /v1/admin/apps/{app_id}/keys`: Create an app (platform) API key

## Webhook payloads

- `POST (webhook: event)`: Event delivery to your endpoint
- `POST (webhook: verify)`: Verify ping