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

# API Overview

> Introduction to Plivo's Messaging API

The Plivo Messaging API lets you programmatically send and receive SMS, MMS, and WhatsApp messages. The API uses standard HTTP methods and returns JSON responses.

## Base URL

```
https://api.plivo.com/v1/Account/{auth_id}/
```

***

## Authentication

All API requests use HTTP Basic Authentication with your Plivo credentials:

* **Username**: Your Auth ID
* **Password**: Your Auth Token

Find your credentials on the [Plivo Console Dashboard](https://cx.plivo.com/home).

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Message/
```

<CodeGroup>
  ```python Python theme={null}
  import plivo

  client = plivo.RestClient('<auth_id>', '<auth_token>')
  ```

  ```javascript Node.js theme={null}
  const plivo = require('plivo');

  const client = new plivo.Client('<auth_id>', '<auth_token>');
  ```

  ```ruby Ruby theme={null}
  require 'plivo'

  api = Plivo::RestClient.new('<auth_id>', '<auth_token>')
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';
  use Plivo\RestClient;

  $client = new RestClient('<auth_id>', '<auth_token>');
  ```

  ```java Java theme={null}
  import com.plivo.api.Plivo;

  Plivo.init("<auth_id>", "<auth_token>");
  ```

  ```csharp .NET theme={null}
  using Plivo;

  var api = new PlivoApi("<auth_id>", "<auth_token>");
  ```

  ```go Go theme={null}
  package main

  import "github.com/plivo/plivo-go/v7"

  func main() {
      client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
  }
  ```
</CodeGroup>

***

## Request Format

* **Content-Type**: `application/json` for POST requests
* **Content-Type**: `multipart/form-data` for media uploads
* All request parameters should be JSON-encoded

```bash theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"src": "+14155551234", "dst": "+14155559876", "text": "Hello!"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/
```

***

## Response Format

All responses are JSON with an `api_id` for request tracking:

```json theme={null}
{
  "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196",
  "message": "message(s) queued",
  "message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"]
}
```

### HTTP Status Codes

| Code  | Description                   |
| ----- | ----------------------------- |
| `200` | Request executed successfully |
| `201` | Resource created              |
| `202` | Resource modified             |
| `204` | Resource deleted              |
| `400` | Invalid or missing parameter  |
| `401` | Authentication failed         |
| `404` | Resource not found            |
| `405` | HTTP method not allowed       |
| `429` | Rate limit exceeded           |
| `500` | Server error                  |

### Troubleshooting Common Errors

| Code  | Common Causes                                                            | Solution                                                                                  |
| ----- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `400` | Missing required parameter (src, dst, text), invalid phone number format | Check all required parameters are included. Use E.164 format for numbers (+14155551234)   |
| `401` | Invalid Auth ID or Auth Token, missing authentication header             | Verify credentials at Console → API Keys. Ensure Basic Auth header is included            |
| `404` | Invalid Message UUID, number not in account, typo in endpoint URL        | Verify the resource UUID exists. Check endpoint spelling                                  |
| `429` | API rate limit exceeded                                                  | Implement exponential backoff. Contact support to increase limits                         |
| `500` | Temporary server issue                                                   | Retry after a few seconds. Check [status.plivo.com](https://status.plivo.com) for outages |

***

## Pagination

List endpoints return paginated results:

```json theme={null}
{
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 100,
    "previous": null,
    "next": "/v1/Account/{auth_id}/Message/?limit=20&offset=20"
  },
  "objects": [...]
}
```

| Parameter | Description                           |
| --------- | ------------------------------------- |
| `limit`   | Results per page (1-20). Default: 20  |
| `offset`  | Number of results to skip. Default: 0 |

***

## API Resources

### Core Resources

| Resource                             | Description                          |
| ------------------------------------ | ------------------------------------ |
| [Messages](/messaging/api/messages/) | Send SMS, MMS, and WhatsApp messages |
| [Media](/messaging/api/media/)       | Upload and manage media for MMS      |

### Powerpack Resources

| Resource                                  | Description                                |
| ----------------------------------------- | ------------------------------------------ |
| [Powerpack](/messaging/api/powerpack/)    | Manage Powerpacks for traffic distribution |
| [Number Pool](/messaging/api/numberpool/) | Manage numbers in Powerpack pools          |

### Compliance Resources

| Resource                                                  | Description                                        |
| --------------------------------------------------------- | -------------------------------------------------- |
| [10DLC](/messaging/api/10dlc/)                            | Register brands and campaigns for US A2P messaging |
| [Toll-free Verification](/messaging/api/tf-verification/) | Verify toll-free numbers for messaging             |

***

## Rate Limits

API requests are rate limited. If you exceed the limit, you'll receive a `429` response. Implement exponential backoff for retries.

***

## Related

* [Quickstart](/messaging/quickstart/quickstart/) - Get started with Messaging API
* [Concepts](/messaging/concepts/overview/) - Messaging fundamentals
* [XML Reference](/messaging/xml/overview/) - Messaging XML elements