API reference
Analytics
4 operations. Base URL: https://api.ringura.com/api/v1. Authenticate with a bearer token that carries the scope named on each operation.
GET /api/v1/exports
Recent exports, newest first.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
limit | query | integer | No | 1 to 200 |
dataset | query | string | No | one of "conversations", "work_items", "dial_attempts", "outcomes", "insights" |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
data | array of object | Yes | |
data[].id | string (uuid) | Yes | |
data[].dataset | string | Yes | one of "conversations", "work_items", "dial_attempts", "outcomes", "insights" |
data[].format | string | Yes | one of "csv", "jsonl", "parquet" |
data[].status | string | Yes | one of "queued", "running", "ready", "failed", "expired" |
data[].via | string | No | one of "console", "api" |
data[].cursorAfter | string or null | Yes | |
data[].rows | integer | Yes | |
data[].bytes | integer | Yes | |
data[].hasMore | boolean | Yes | |
data[].nextCursor | string or null | Yes | |
data[].snapshotUntil | string (date-time) or null | No | |
data[].error | string or null | No | |
data[].createdAt | string (date-time) | Yes | |
data[].finishedAt | string (date-time) or null | No | |
data[].expiresAt | string (date-time) or null | No |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/exports' \
-H "Authorization: Bearer $CC_TOKEN"POST /api/v1/exports
Queue an export of a dataset (conversations, work_items, dial_attempts, outcomes, insights) as CSV, JSON lines or Parquet. Start from a time (since), from the watermark of a previous export (cursor), or from the beginning. It is built asynchronously; an export.ready webhook (or polling GET /exports/{id}) says when to download.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
Idempotency-Key | header | string | No | matches ^[A-Za-z0-9_.:-]{8,100}$ |
Request body
JSON (Content-Type: application/json).
| Field | Type | Required | Constraints |
|---|---|---|---|
dataset | string | Yes | one of "conversations", "work_items", "dial_attempts", "outcomes", "insights" |
format | string | No | one of "csv", "jsonl", "parquet" |
cursor | string | No | at most 100 characters |
since | string (date-time) | No |
Response
202 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
dataset | string | Yes | one of "conversations", "work_items", "dial_attempts", "outcomes", "insights" |
format | string | Yes | one of "csv", "jsonl", "parquet" |
status | string | Yes | one of "queued", "running", "ready", "failed", "expired" |
via | string | No | one of "console", "api" |
cursorAfter | string or null | Yes | |
rows | integer | Yes | |
bytes | integer | Yes | |
hasMore | boolean | Yes | |
nextCursor | string or null | Yes | |
snapshotUntil | string (date-time) or null | No | |
error | string or null | No | |
createdAt | string (date-time) | Yes | |
finishedAt | string (date-time) or null | No | |
expiresAt | string (date-time) or null | No |
Errors
400, 401, 403, 404, 409, 422, 429. What each status means
Example request
curl -X POST 'https://api.ringura.com/api/v1/exports' \
-H "Authorization: Bearer $CC_TOKEN" \
-H 'Idempotency-Key: order-2027-0001' \
-H 'Content-Type: application/json' \
-d '{
"dataset": "conversations"
}'GET /api/v1/exports/{id}
One export: its status, size, row count and the watermark to start the next pull from.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes |
Response
200 JSON with these fields.
| Field | Type | Required | Constraints |
|---|---|---|---|
id | string (uuid) | Yes | |
dataset | string | Yes | one of "conversations", "work_items", "dial_attempts", "outcomes", "insights" |
format | string | Yes | one of "csv", "jsonl", "parquet" |
status | string | Yes | one of "queued", "running", "ready", "failed", "expired" |
via | string | No | one of "console", "api" |
cursorAfter | string or null | Yes | |
rows | integer | Yes | |
bytes | integer | Yes | |
hasMore | boolean | Yes | |
nextCursor | string or null | Yes | |
snapshotUntil | string (date-time) or null | No | |
error | string or null | No | |
createdAt | string (date-time) | Yes | |
finishedAt | string (date-time) or null | No | |
expiresAt | string (date-time) or null | No |
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/exports/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e' \
-H "Authorization: Bearer $CC_TOKEN"GET /api/v1/exports/{id}/download
The finished export as text/csv, application/x-ndjson or application/vnd.apache.parquet. X-Export-Watermark carries the watermark for the next pull and X-Export-Has-More says to pull again at once.
Parameters
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
id | path | string (uuid) | Yes |
Response
200 A string. Also available as text/csv, application/x-ndjson, application/vnd.apache.parquet.
Errors
400, 401, 403, 404, 409, 429. What each status means
Example request
curl -X GET 'https://api.ringura.com/api/v1/exports/0192f5a0-7c1e-7d3a-9b2e-3f4a5b6c7d8e/download' \
-H "Authorization: Bearer $CC_TOKEN"