> For the complete documentation index, see [llms.txt](https://docs.sms4sats.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sms4sats.com/api-reference/api-reference.md).

# Overview

Complete endpoint map and conventions for sms4sats API v2.

## Base URL

```
https://api.sms4sats.com
```

Requests and responses use JSON unless otherwise noted. Send `Content-Type: application/json` with JSON bodies.

## Documented client integration endpoints

### Service discovery

| Method | Path                         | Purpose                    |
| ------ | ---------------------------- | -------------------------- |
| `GET`  | `/health`                    | API and database health    |
| `GET`  | `/v2/browser`                | Bearer-token API discovery |
| `GET`  | `/v2/l402`                   | L402 API discovery         |
| `GET`  | `/.well-known/l402-services` | L402 service discovery     |

### Bearer-token SMS

| Method | Path                                 | Purpose                   |
| ------ | ------------------------------------ | ------------------------- |
| `GET`  | `/v2/receive-sms/catalog`            | Supported service codes   |
| `POST` | `/v2/receive-sms/quote`              | Live receive-SMS quote    |
| `POST` | `/v2/receive-sms/orders`             | Create hold-invoice order |
| `GET`  | `/v2/receive-sms/orders/{id}`        | Poll protected order      |
| `POST` | `/v2/receive-sms/orders/{id}/cancel` | Cancel eligible order     |

### Bearer-token rentals

| Method | Path                                  | Purpose                                    |
| ------ | ------------------------------------- | ------------------------------------------ |
| `GET`  | `/v2/rent-numbers/catalog`            | Rental countries, availability, and prices |
| `POST` | `/v2/rent-numbers/quote`              | Live rental quote                          |
| `POST` | `/v2/rent-numbers/orders`             | Create rental order                        |
| `GET`  | `/v2/rent-numbers/orders/{id}`        | Poll rental order                          |
| `POST` | `/v2/rent-numbers/orders/{id}/cancel` | Cancel an unpaid rental                    |

### Email activations

| Method   | Path                        | Purpose                                                                   |
| -------- | --------------------------- | ------------------------------------------------------------------------- |
| `GET`    | `/v2/emails/domains?site=…` | Available domains and prices                                              |
| `POST`   | `/v2/emails`                | Create hold-invoice email order                                           |
| `GET`    | `/v2/emails/{id}`           | Poll protected email order                                                |
| `POST`   | `/v2/emails/{id}/reorder`   | Reuse an assigned email for another activation                            |
| `POST`   | `/v2/emails/{id}/cancel`    | Cancel an eligible email order                                            |
| `DELETE` | `/v2/emails/{id}`           | Server-side cancellation alias; browser CORS permits `POST`, not `DELETE` |

### L402

| Method | Path                         | Purpose                                      |
| ------ | ---------------------------- | -------------------------------------------- |
| `GET`  | `/v2/l402/services`          | Service codes                                |
| `GET`  | `/v2/l402/catalog`           | Cached receive-SMS and reactivation offers   |
| `POST` | `/v2/l402/order`             | Create an L402 order/challenge               |
| `GET`  | `/v2/l402/order/{id}`        | Authenticate, allocate, and poll             |
| `POST` | `/v2/l402/order/{id}/cancel` | Cancel and refund eligible receive-SMS order |

Verification, analytics-ingestion, dashboard, and provider/webhook callback routes are operational endpoints rather than client integration contracts and are intentionally omitted. Do not build customer integrations against them.

## Global limits

* Global rate limit: **300 requests per minute per client**.
* Bearer-token order creation: **60 requests per minute per client**.
* JSON request bodies are limited to **200 KB**.
* Rate-limit responses use HTTP `429` and standard rate-limit headers.

## Health response

```json
{
  "status": "ok",
  "orderStatus": "healthy",
  "dbStatus": "up",
  "timestamp": "2026-09-30T19:00:00.000Z"
}
```