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

# API Reference Overview

> Complete guide to the NativeMessage REST API

## Base URL

All API requests use the following base URL:

```
https://api-message.nativehub.live/api/v1
```

## Versioning

The API is currently at **v1**, which is the only available version. Version information is included in the URL path.

## Content Type

All API requests and responses use `application/json` format. Include the following header in all requests:

```
Content-Type: application/json
```

## Authentication

NativeMessage API supports two authentication methods:

* **JWT Bearer Token**: Include `Authorization: Bearer <token>` header
* **API Key**: Include `X-API-Key: <your-api-key>` header

<Info>
  See the [Authentication](/authentication) guide for detailed setup instructions.
</Info>

## Pagination

List endpoints support pagination using query parameters:

| Parameter  | Description              | Default | Max |
| ---------- | ------------------------ | ------- | --- |
| `page`     | Page number to retrieve  | 1       | -   |
| `per_page` | Number of items per page | 20      | 100 |

**Example Request:**

```
GET /api/v1/messages?page=2&per_page=50
```

**Pagination Response Format:**

```json theme={null}
{
  "data": [...],
  "total": 247,
  "page": 2,
  "per_page": 50
}
```

## Response Format

### Success Response (Single Resource)

```json theme={null}
{
  "id": "msg_abc123",
  "status": "delivered",
  "created_at": "2026-02-14T10:30:00Z"
}
```

### Success Response (List)

```json theme={null}
{
  "data": [
    { "id": "msg_1", "status": "delivered" },
    { "id": "msg_2", "status": "pending" }
  ],
  "total": 247,
  "page": 1,
  "per_page": 20
}
```

### Error Response

```json theme={null}
{
  "error": "Invalid phone number format"
}
```

## HTTP Status Codes

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 200  | OK - Request succeeded                           |
| 201  | Created - Resource successfully created          |
| 400  | Bad Request - Invalid request parameters         |
| 401  | Unauthorized - Missing or invalid authentication |
| 403  | Forbidden - Insufficient permissions             |
| 404  | Not Found - Resource does not exist              |
| 429  | Too Many Requests - Rate limit exceeded          |
| 500  | Internal Server Error - Server-side error        |

## Rate Limiting

API requests are limited to **200 requests per minute** per tenant. When exceeded, the API returns a `429` status code.

<Info>
  See the [Rate Limits](/guides/rate-limits) guide for best practices and optimization strategies.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Set up API keys and JWT tokens
  </Card>

  <Card title="Send a Message" icon="paper-plane" href="/quickstart">
    Send your first SMS in 5 minutes
  </Card>

  <Card title="API Endpoints" icon="code" href="/api-reference/messages/send">
    Browse available endpoints
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Receive delivery reports in real-time
  </Card>
</CardGroup>