> ## Documentation Index > Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt > Use this file to discover all available pages before exploring further. # CloudTalk REST API v1.7 — Complete Developer Reference > Complete reference for CloudTalk REST API v1.7. All endpoints use HTTP Basic Auth; core endpoints wrap payloads in a responseData envelope, while the Dialer partner API has its own base URL and response shape. The CloudTalk REST API v1.7 gives you programmatic access to your call center data and operations. It is organized around resources — Calls, Contacts, Agents, Numbers, and more — and follows predictable, resource-oriented URL conventions. All requests must be made over HTTPS, and responses are returned as UTF-8 encoded JSON. Core endpoints wrap payloads in a `responseData` envelope; some specialized surfaces differ — see the notes below. ## Base URLs Most API endpoints share a single base URL. A handful of specialized capabilities — detailed analytics, AI features, and real-time agent guidance — use their own dedicated hosts. | Purpose | Base URL | | -------------------------------------------- | ----------------------------------------- | | Standard API (calls, contacts, agents, etc.) | `https://my.cloudtalk.io/api/` | | Detailed call flow analytics | `https://analytics-api.cloudtalk.io/api/` | | Conversation Intelligence & VoiceAgent (AI) | `https://api.cloudtalk.io/v1/` | | CueCard (real-time agent guidance) | `https://platform-api.cloudtalk.io/api/` | | Dialer partner API | `https://api.cloudtalk.io/v1` | Always use the correct base URL for the resource you are accessing. Using the wrong host will result in a `404` response even if the path is correct. ## Authentication Every request to the CloudTalk API must include HTTP Basic Auth credentials — the same key pair on every host. Use your **API Access Key ID** as the username and your **API Access Key Secret** as the password. ```bash theme={"system"} curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \ https://my.cloudtalk.io/api/calls/index.json ``` Only Administrators can create API keys. You can generate and manage them in the CloudTalk Dashboard under **Account → Settings → API Keys** ([open directly](https://dashboard.cloudtalk.io/menu/account/settings/API-keys)). Keep your API credentials secure. Do not commit them to source control or expose them in client-side code. Rotate your credentials immediately if they are compromised. ## Response Envelope All successful responses from the standard API are wrapped in a top-level `responseData` object. Paginated collection endpoints include pagination metadata alongside the `data` array. ```json theme={"system"} { "responseData": { "itemsCount": 100, "pageCount": 2, "pageNumber": 1, "limit": 50, "data": [ ... ] } } ``` Single-resource responses omit the pagination fields and return the resource object directly inside `responseData`. ```json theme={"system"} { "responseData": { "id": "42", "status": "answered", ... } } ``` ## HTTP Methods **The core API does not use `POST` and `PUT` the way most REST APIs do.** On `my.cloudtalk.io/api`, **`PUT` creates** and **`POST` updates** — the reverse of the usual convention. Reaching for `POST` to create a resource will not work. | Method | Usage on the core API (`my.cloudtalk.io/api`) | | -------- | ------------------------------------------------------------------------------ | | `GET` | Access a resource and perform queries. Never modifies data. | | `PUT` | **Create** a resource — e.g. `PUT /agents/add.json`, `PUT /contacts/add.json`. | | `POST` | **Update** an existing resource — e.g. `POST /agents/edit/{agentId}.json`. | | `DELETE` | Delete a resource. | Three core endpoints are actions rather than updates, and use `POST` for that: [Make a call](/api-reference/calls/make-a-call), [Send sms](/api-reference/sms/send-sms) and [Contact actions](/api-reference/bulks/contact-actions). `PATCH` is not used by the core API. ### Newer surfaces use conventional REST The newer surfaces follow the usual convention, but most expose only a slice of it: Conversation Intelligence is read-only, and VoiceAgent and CueCard are `POST`-only. Dialer is the only surface with `PATCH`, `PUT` or `DELETE` operations: | Method | Usage | | -------- | ----------------------------------------------------------------------------------------------- | | `GET` | Retrieve a resource or a list of resources | | `POST` | Create a resource or trigger an action | | `PATCH` | Partially update an existing resource | | `PUT` | Replace a sub-collection wholesale (Dialer associations, disposition buttons, survey questions) | | `DELETE` | Delete a resource | ## Error Handling When a request fails, CloudTalk returns an appropriate HTTP status code along with a JSON body describing the error. ```json theme={"system"} { "responseData": { "status": 404, "message": "Call not found" } } ``` Common status codes you will encounter across all endpoints: | Status | Meaning | | ------ | -------------------------------------------------------- | | `200` | Success | | `400` | Bad request — malformed parameters | | `401` | Unauthorized — missing or invalid credentials | | `403` | Forbidden — action not permitted for this account | | `404` | Not found — resource does not exist | | `406` | Not acceptable — invalid input value | | `409` | Conflict — resource state prevents this action | | `410` | Gone — resource existed but has been permanently deleted | | `429` | Too many requests — rate limit exceeded | | `500` | Internal server error | ## Pagination Collection endpoints support pagination via `limit` and `page` query parameters. The response envelope includes `itemsCount`, `pageCount`, and `pageNumber` fields to help you iterate through large result sets. ```bash theme={"system"} # Fetch page 2 with 100 items per page curl -u YOUR_KEY_ID:YOUR_KEY_SECRET \ 'https://my.cloudtalk.io/api/calls/index.json?limit=100&page=2' ``` The maximum value for `limit` is `1000`. ## Resources The API is divided into the following resource groups: Access call history, download recordings, initiate outbound calls, and retrieve real-time group statistics. Create, update, and delete contacts. Manage tags, notes, and contact activity history. Manage agent accounts, update agent details, and control group memberships. List and configure the phone numbers assigned to your CloudTalk account. Create and manage agent groups, including group membership and routing rules. Send outbound SMS messages and WhatsApp messages to contacts. Create and manage tags that can be applied to calls and contacts for classification. Manage outbound dialer campaigns including power dialer and predictive dialer configurations. Perform batch operations on contacts, such as bulk import and bulk tagging. Deliver real-time agent guidance cards during live calls via the CueCard platform API. Access AI-powered call analysis including summaries, full transcriptions, and sentiment scores. Initiate AI voice agent calls programmatically, and stop outbound VoiceAgent dialing in an emergency. Manage sales-dialer campaigns, contacts, call scripts, surveys, disposition buttons, statistics, and exports. Separate base URL and response shape; same Basic-auth credentials. Access supporting data such as the countries list and manage the inbound call blacklist. ## Rate Limits CloudTalk enforces rate limits to ensure platform stability. If you exceed the allowed request rate, the API returns a `429 Too Many Requests` response. Implement exponential backoff in your integration to handle transient rate-limit errors gracefully. For high-volume integrations, batch your requests using the Bulks endpoints where available, and cache reference data (agents, groups, tags) locally rather than fetching it on every request. ## Related topics - [CloudTalk REST API: Call Center Automation Platform](/guides/introduction.md) - [CloudTalk API Rate Limits, Headers, and Throttling](/guides/rate-limiting.md) - [CloudTalk API Response Envelope Formats and Schema](/guides/response-envelopes.md)