CallX API Reference
API Version: v1.0The CallX API follows RESTful principles with JSON request and response payloads. This reference provides comprehensive details about endpoints, authentication methods, request formats, and responses.
Authentication
The CallX API uses API keys for authentication. All API requests must include your API key in the header.
X-API-Key: your_api_key_here
OAuth 2.0 Authentication
For user-based actions, you can also use OAuth 2.0. The following scopes are supported:
| Scope | Description |
|---|---|
| user.read | Read user profile information |
| messages.read | Read user conversations and messages |
| messages.write | Send messages on behalf of the user |
| calls.read | Read user call history |
| calls.write | Initiate calls on behalf of the user |
Endpoints
Messages
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/messages | List messages in a conversation |
| POST | /openapi/messages | Send a new message |
| GET | /openapi/messages/{id} | Get a specific message by ID |
| DELETE | /openapi/messages/{id} | Delete a message |
Conversations
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/conversations | List conversations |
| POST | /openapi/conversations | Create a new conversation |
| GET | /openapi/conversations/{id} | Get a specific conversation by ID |
| DELETE | /openapi/conversations/{id} | Delete a conversation |
Users
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/users/me | Get authenticated user profile |
| PATCH | /openapi/users/me | Update authenticated user profile |
| GET | /openapi/users/{id} | Get user by ID |
Calls
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/calls | List call history |
| POST | /openapi/calls | Initiate a new call |
| GET | /openapi/calls/{id} | Get call details by ID |
| POST | /openapi/calls/{id}/end | End an active call |
Broadcasts
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/broadcasts | List broadcasts |
| POST | /openapi/broadcasts | Create a new broadcast |
| GET | /openapi/broadcasts/{id} | Get broadcast details |
| DELETE | /openapi/broadcasts/{id} | Cancel a broadcast |
Locations
| Method | Endpoint | Description |
|---|---|---|
| GET | /openapi/locations | Get user location history |
| POST | /openapi/locations | Update a user's location |
| GET | /openapi/locations/tracking | Get active location tracking sessions |
| POST | /openapi/locations/tracking | Start a location tracking session |
Parameters
The CallX API accepts various parameters to filter, sort, and paginate results:
Common Query Parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | Page number for paginated results (default: 1) |
| limit | integer | Number of items per page (default: 20, max: 100) |
| sort | string | Field to sort by (e.g., created_at, updated_at) |
| order | string | Sort order (asc or desc, default: desc) |
| filter | string | Filter expression (e.g., status:active) |
Responses
All API responses are returned in JSON format. Successful requests will receive the appropriate HTTP status code and a response body.
Pagination
List endpoints return paginated results with the following structure:
{
"data": [...], // Array of items
"meta": {
"current_page": 1,
"total_pages": 5,
"total_items": 100,
"items_per_page": 20
},
"links": {
"first": "/openapi/resource?page=1",
"prev": null,
"next": "/openapi/resource?page=2",
"last": "/openapi/resource?page=5"
}
}
Errors
When an error occurs, the API returns an appropriate HTTP status code and a JSON response with error details:
{
"error": "access_denied",
"message": "Insufficient permissions to access this resource",
"details": {
"required": ["messages:read"],
"provided": ["user:read"]
}
}
Common Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | The request was malformed or contained invalid parameters |
| 401 | unauthorized | Authentication credentials were missing or invalid |
| 403 | access_denied | The authenticated user does not have sufficient permissions |
| 404 | not_found | The requested resource was not found |
| 429 | rate_limit_exceeded | The API rate limit has been exceeded |
| 500 | server_error | An unexpected server error occurred |
Examples
Sending a Message
POST
/openapi/messages
Sends a new message to a conversation.
Request Headers
X-API-Key: your_api_key_here Content-Type: application/json
Request Body
{
"conversation_id": "12345678-1234-1234-1234-123456789012",
"text": "Hello, world!",
"attachments": []
}
Response
{
"id": "87654321-4321-4321-4321-210987654321",
"conversation_id": "12345678-1234-1234-1234-123456789012",
"sender_id": "98765432-6543-6543-6543-987654321098",
"text": "Hello, world!",
"attachments": [],
"read_by": [],
"created_at": "2025-05-14T10:30:00Z",
"updated_at": "2025-05-14T10:30:00Z"
}
Getting User Profile
GET
/openapi/users/me
Retrieves the profile of the authenticated user.
Request Headers
X-API-Key: your_api_key_here
Response
{
"id": "98765432-6543-6543-6543-987654321098",
"username": "johndoe",
"display_name": "John Doe",
"email": "john.doe@example.com",
"profile_image": "https://callx.us/users/98765432-6543-6543-6543-987654321098/avatar",
"status": "active",
"created_at": "2025-01-01T00:00:00Z",
"updated_at": "2025-05-01T12:00:00Z"
}