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

# API overview

> Complete reference for the Messaging Platform API

## Introduction

The Messaging Platform API provides a comprehensive set of endpoints for sending and receiving SMS/MMS messages, managing workspaces, and configuring phone numbers.

## Base URL

All API requests should be made to:

```
https://api.yourdomain.com
```

## Authentication

The API uses two types of authentication:

### API key authentication

For programmatic access to messaging endpoints:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

API keys can be generated from the workspace settings in the UI.

### Session authentication

For UI-based endpoints that require user context:

```bash theme={null}
Authorization: Bearer YOUR_SESSION_TOKEN
```

Session tokens are obtained through the authentication flow.

## API Categories

<CardGroup cols={2}>
  <Card title="Messaging" icon="message" href="/api-reference/messaging/send-message">
    Send SMS and MMS messages programmatically
  </Card>

  <Card title="Workspaces" icon="folder" href="/api-reference/workspaces/update-workspace">
    Manage workspace settings and configurations
  </Card>
</CardGroup>

## Rate limits

API endpoints are subject to rate limiting to ensure service stability:

* **Messaging API**: 100 requests per minute per API key
* **UI APIs**: 1000 requests per minute per user

Rate limit information is returned in response headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642521600
```

## Error handling

All API errors follow a consistent format:

```json theme={null}
{
  "error": "error_code",
  "detail": "Human-readable error description"
}
```

Common HTTP status codes:

* `200` - Success
* `201` - Created
* `400` - Bad Request
* `401` - Unauthorized
* `403` - Forbidden
* `404` - Not Found
* `429` - Too Many Requests
* `500` - Internal Server Error
* `503` - Service Unavailable

## Pagination

List endpoints support pagination using query parameters:

```
GET /api/ui/workspaces/{workspaceId}/messages?page=1&limit=50
```

Paginated responses include metadata:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalItems": 487,
    "hasNext": true
  }
}
```

## Real-time updates

The platform supports real-time message updates via WebSocket connections. Messages and status updates are automatically broadcast to connected clients for instant UI updates.

## SDK support

While we don't currently provide official SDKs, the API is designed to work with standard HTTP clients in any programming language. See the request examples in each endpoint documentation for language-specific implementations.

## Getting started

1. **Create a workspace**: Sign up and create your first workspace
2. **Generate an API key**: Go to workspace settings to create an API key
3. **Configure your messaging provider**: Add your provider credentials in workspace settings
4. **Send a test message**: Use the `/api/messages` endpoint to send your first message

## Support

For API support and questions:

* Check the individual endpoint documentation
* Review error messages and codes
* Contact support at [support@yourdomain.com](mailto:support@yourdomain.com)