> ## 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 API Response Envelope Formats and Schema
> Core CloudTalk API responses use a responseData envelope. Learn the single-item, collection, and error formats, plus the shapes used by Analytics, Conversation Intelligence, VoiceAgent, CueCard and Dialer.
Structured responses from the CloudTalk REST API (v1.7) are JSON documents encoded in UTF-8 per [RFC 8259](https://www.rfc-editor.org/rfc/rfc8259). On the **core API** at `my.cloudtalk.io/api`, the top-level key is `responseData`. Understanding the three envelope shapes — single-item, collection, and error — lets you write one parsing layer that handles most core API responses your integration receives.
The `responseData` envelope is a **core API** convention, not a platform-wide contract. Call Flow Analytics, Conversation Intelligence, VoiceAgent, CueCard and Dialer each use their own top-level structure — see [Envelope Exceptions](#envelope-exceptions). Endpoints that return binary content, such as [Recording media](/api-reference/calls/recording-media) (`audio/x-wav`), return no envelope at all.
## Envelope Types
The CloudTalk API uses three distinct envelope shapes depending on the nature of the request. Each is described below with its full field reference and a representative JSON example.
### Single-Item Envelope
When you request or mutate a single resource on the core API, the API commonly returns an HTTP `200` status and wraps the resource object directly inside `responseData`. There are no pagination fields — you receive only the object itself.
```json Single-item response theme={"system"}
{
"responseData": {
"id": 123,
"created": "2018-01-10 12:34:56"
}
}
```
The root envelope object for single-item core API responses.
The unique identifier of the returned resource.
UTC timestamp recording when the resource was created, e.g. `2018-01-10 12:34:56`.
A `200` does not always carry a resource. [Make a call](/api-reference/calls/make-a-call) returns `{"responseData": {"status": 200}}` and no call record. Core `PUT` create endpoints return `201`; some newer endpoints return `204` with no body at all. Read the status codes and schema on the endpoint's own reference page.
***
### Collections Envelope
When you query a **paginated** core API list endpoint, the API returns an HTTP `200` status and wraps the result set inside `responseData`, together with four pagination metadata fields alongside the `data` array so you can determine how many pages remain. See the [Pagination guide](/guides/pagination) for iteration patterns.
```json Collection response theme={"system"}
{
"responseData": {
"itemsCount": 65,
"pageCount": 3,
"pageNumber": 1,
"limit": 30,
"data": [
{ "id": 123, "created": "2018-01-10 12:34:56" },
{ "id": 456, "created": "2017-10-19 09:21:29" }
]
}
}
```
The root envelope object for collection responses.
Total number of resources that match the query across **all** pages.
Total number of pages available given the current `limit`.
The current page number returned in this response (1-indexed).
Maximum number of items per page, as applied by the server. Send `limit` (`1`–`1000`) to set it; omit it and the server applies its own default, which this field reports back to you.
The array of resource objects for the current page. Each element's schema varies by endpoint.
Not every collection endpoint paginates. [List countries](/api-reference/utilities/list-countries) puts a plain array directly in `responseData`, with no `itemsCount`, `pageCount`, `pageNumber` or `limit`. Treat the four pagination fields as present only where the endpoint documents them.
***
### Error Envelope
When a request to the core API fails, it returns an appropriate HTTP error status code and wraps a short diagnostic payload inside `responseData`. The `status` field mirrors the HTTP status code, and `message` provides a human-readable description. The other surfaces use different error shapes — see the [Error Codes reference](/guides/error-codes).
```json Error response theme={"system"}
{
"responseData": {
"status": 404,
"message": "Not Found"
}
}
```
The root envelope object for error responses.
The HTTP status code that describes the error, e.g. `400`, `401`, `404`, `429`.
A short, human-readable description of the error. Use this field for logging and debugging.
For a complete list of status codes, their meanings, and remediation steps, see the [Error Codes reference](/guides/error-codes).
***
## Dates and Timestamps
All date and time values are expressed in **UTC**, but the exact wire representation varies by endpoint — take it from the endpoint's own reference page. Both of these forms appear in the API:
```text Timestamp formats in use theme={"system"}
YYYY-MM-DD HH:MM:SS → 2018-01-10 12:34:56 envelope examples; the
date_from / date_to filters
YYYY-MM-DDTHH:MM:SS.sssZ → 2017-10-04T06:33:37.000Z call record fields such
as started_at, ended_at
```
When you store or compare timestamps, ensure your application treats them as UTC to avoid off-by-one-hour bugs around daylight saving transitions.
***
## Envelope Exceptions
The `responseData` envelope belongs to the core API. Every other surface has its own shape — use this matrix, then confirm against the endpoint's reference page.
| Surface | Base URL | Success shape | Error shape |
| ----------------------------- | -------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Core API** | `my.cloudtalk.io/api` | `responseData` — single item, or a collection with pagination where documented | `{"responseData": {"status", "message"}}` |
| **Recording media** | `my.cloudtalk.io/api` | Binary `audio/x-wav`, no envelope | `{"responseData": {"status", "message"}}` |
| **Call Flow Analytics** | `analytics-api.cloudtalk.io/api` | Direct JSON object, no envelope | `{"statusCode", "message", "error"}` |
| **Conversation Intelligence** | `api.cloudtalk.io/v1` | Direct per-call object; Topics and Transcription add `{ data, pagination }` | `401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId"}` |
| **VoiceAgent** | `api.cloudtalk.io/v1` | `204` with no body on initiate; a direct JSON object on the outbound kill switch | `401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId"}` |
| **CueCard** | `platform-api.cloudtalk.io/api` | `{"success": true}` | `{"success": false, "errors": [...]}` |
| **Dialer** | `api.cloudtalk.io/v1` | Varies — see below | `401`: `{"code", "message"}` · others: `{"statusCode", "message", "error", "correlationId", "subErrors?"}` |
### Dialer
**Dialer endpoints do not follow the `responseData` envelope**, and they do not share one shape either. What you get depends on the operation:
* **List endpoints** return `{ "data": [...], "meta": { "nextCursor": "..." } }`. Pass a returned `meta.nextCursor` back as the `cursor` query parameter to fetch the next page; a `null` cursor means there are no more pages.
* **Single-resource endpoints** return the object directly — `GET /dialer/campaigns/{campaignId}` returns a campaign, not a wrapper.
* **Some sub-collections** return a plain array — `GET /dialer/campaigns/{campaignId}/disposition-buttons`, for example.
* **Creates** return `201` with the created object. **Export requests** return `202` with `{ "jobId", "status" }`. **Deletes** return `204` with no body.
### Conversation Intelligence
**Conversation Intelligence is organized per call, not as a collection of calls.** Each endpoint takes a call ID — `/ai/calls/{callId}/summary`, `/overall-sentiment`, `/talk-listen-ratio`, `/topics`, `/transcription`, `/smart-notes`, `/details-link` — and returns a direct JSON object at the top level with no `responseData` wrapper.
Most CI endpoints return their payload flat:
```json Overall sentiment theme={"system"}
{
"callId": 12345,
"overallSentiment": "positive"
}
```
**Topics** and **Transcription** are the two that paginate — over the content of a single call, not over calls. They nest the payload under `data` and add a sibling `pagination` object:
```json Transcription (abridged) theme={"system"}
{
"data": {
"callId": 12345,
"segments": [
{ "start": 1.501, "end": 4.599, "caller": "caller2", "text": "Hello, I would like to ask for help." }
],
"callers": [
{ "id": 5000, "type": "contact", "localIdentifier": "caller1" }
],
"language": "en"
},
"pagination": { "limit": 1, "offset": 0, "total": 10 }
}
```
### Call Flow Analytics
[Get call details](/api-reference/calls/get-call-details) is served by `analytics-api.cloudtalk.io` and returns its payload as a direct JSON object — `{ "cdr_id": 12345, "uuid": "...", "contact": {...}, ... }` — with no `responseData` wrapper. Its errors use `{ "statusCode", "message", "error" }`.
### CueCard
The **CueCard endpoint** also bypasses the standard envelope format. On success it returns `{"success": true}` directly; on failure, `{"success": false, "errors": ["..."]}`.
***
## Quick Reference
Core API. Usually HTTP `200` with the resource object inside `responseData`, no pagination metadata — but check for `201`, `204` and status-only bodies.
Core API, where the endpoint documents pagination. HTTP `200` with `itemsCount`, `pageCount`, `pageNumber`, `limit`, and a `data` array.
Core API. HTTP `4xx` / `5xx` with `status` (mirrors HTTP code) and a human-readable `message`. Other surfaces differ — see the matrix above.
## Related topics
- [How to Paginate CloudTalk API Collection Responses](/guides/pagination.md)
- [CloudTalk API HTTP Error Codes: Causes and Resolutions](/guides/error-codes.md)
- [Quickstart: Make Your First CloudTalk REST API Call](/guides/quickstart.md)