> ## 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/
```

```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{})
}
```

***

## 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](https://plivo.com/docs/messaging/api/messages.md) | Send SMS, MMS, and WhatsApp messages |
| [Media](https://plivo.com/docs/messaging/api/media.md) | Upload and manage media for MMS |

### Powerpack Resources

| Resource | Description |
| - | - |
| [Powerpack](https://plivo.com/docs/messaging/api/powerpack.md) | Manage Powerpacks for traffic distribution |
| [Number Pool](https://plivo.com/docs/messaging/api/numberpool.md) | Manage numbers in Powerpack pools |

### Compliance Resources

| Resource | Description |
| - | - |
| [10DLC](https://plivo.com/docs/messaging/api/10dlc/) | Register brands and campaigns for US A2P messaging |
| [Toll-free Verification](https://plivo.com/docs/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](https://plivo.com/docs/messaging/quickstart/quickstart.md) - Get started with Messaging API
* [Concepts](https://plivo.com/docs/messaging/concepts/overview.md) - Messaging fundamentals
* [XML Reference](https://plivo.com/docs/messaging/xml/overview.md) - Messaging XML elements