# About the PressOne API

The PressOne API provides programmable access to telecommunications infrastructure. Use these RESTful endpoints to build voice, messaging, and communication workflows into your applications.

## API architecture

The PressOne API follows REST conventions with predictable resource-oriented URLs. All requests and responses use JSON format.

### Base URLs

| Environment | Base URL | Purpose |
|-------------|----------|---------|
| Production | `https://api.helios.pressone.co` | Live traffic with real phone numbers |
| Sandbox | `https://sandbox.api.helios.pressone.co` | Testing with simulated call flows |

Use the sandbox environment during development. Sandbox mirrors production functionality but uses test phone numbers and does not incur charges.

### Request format

All API requests must include:

- **HTTPS**: TLS encryption is required for all requests
- **Content-Type**: `application/json` for request bodies
- **Authorization**: HTTP Basic authentication header

```bash
curl https://api.helios.pressone.co/api/v1/calls \
  -u ACCOUNT_SID:AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2341000000001",
    "message": "Your verification code is 123456"
  }'
```

### Response format

Successful responses return JSON with the requested data:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "to": "+2341000000001",
  "created_at": "2024-01-15T10:30:00Z"
}
```

Error responses include a status code and error details:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'to' field must be a valid E.164 phone number"
  }
}
```

## Pagination

List endpoints return paginated results. Control pagination with query parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 0 | Zero-indexed page number |
| `page_size` | integer | 50 | Results per page (max 100) |

```bash
curl -u ACCOUNT_SID:AUTH_TOKEN \
  "https://api.helios.pressone.co/api/v1/calls?page=0&page_size=25"
```

## Rate limits

API requests are subject to rate limits to ensure platform stability. When you exceed the limit, the API returns a `429` status code.

Rate limit headers in responses:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per window |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

Implement exponential backoff when receiving `429` responses.



Webhook payloads are signed for verification. See the [Authentication](/authentication) guide for webhook signature validation.

## Next steps

- [Authentication](/authentication) - Credential management and security
- [API Reference](/api/chatterwave) - Complete endpoint documentation