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

# API Reference Overview

> Base URL, authentication, rate limits, and error handling

# API Reference

The Oktivo API enables programmatic access to voice calling, token management, and webhook configuration.

## Base URL

```
https://client-backend.oktivo.com
```

All API endpoints are served over HTTPS. HTTP requests are rejected.

## Authentication

| Endpoint Group | Auth Method | Header |
| - | - | - |
| `/api/v1/crm/calls/*` | API Token or JWT | `Authorization: Bearer okt_...` |
| `/api/v1/crm/tokens/*` | JWT only | `Authorization: Bearer <jwt>` |
| `/webhooks/endpoints/*` | JWT only | `Authorization: Bearer <jwt>` |

See [Authentication](https://stage-docs.oktivo.com/authentication.md) for details on token creation and management.

## Rate Limits

| Endpoint | Limit |
| - | - |
| `POST /api/v1/crm/calls` | 60 requests/minute per account |
| All other endpoints | 120 requests/minute per account |

When rate limited, you'll receive a `429` response with a `Retry-After` header indicating how many seconds to wait.

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded. Try again in 45 seconds."
}
```

## Error Format

All error responses follow a consistent structure:

```json theme={null}
{
  "success": false,
  "message": "Human-readable error description",
  "errors": [
    {
      "field": "phone",
      "message": "phone must be in E.164 format (e.g. +14155551234)"
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Always `false` for errors |
| `message` | string | Summary of what went wrong |
| `errors` | array | Optional field-level validation errors |

## HTTP Status Codes

| Code | Meaning |
| - | - |
| 200 | Success |
| 201 | Created (new resource) |
| 400 | Validation error check the `errors` array |
| 401 | Unauthorized invalid or missing token |
| 402 | Insufficient credits |
| 404 | Resource not found |
| 409 | Conflict resource is in an incompatible state |
| 429 | Rate limited wait and retry |
| 500 | Internal server error |
| 503 | Service unavailable retry with backoff |

## Pagination

List endpoints return all results for the authenticated user. For endpoints with large result sets, pagination is indicated by:

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 127,
    "hasMore": true
  }
}
```

Use `?page=2&pageSize=50` query parameters to navigate pages.

## Request Format

* All request bodies must be JSON (`Content-Type: application/json`)
* Path parameters are included in the URL (e.g., `/calls/{contactUID}`)
* Query parameters are used for filtering and pagination

## API Versioning

The current API version is **v1**. The version is included in the URL path:

```
https://client-backend.oktivo.com/api/v1/crm/calls
```

Breaking changes will be introduced in new versions. The current version will remain supported with advance deprecation notice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.