Private CDN URLs (`transcription_url`, `recap_url`, `audio_url`, `video_url`, and other Ringover CDN download links) cannot be opened with a public API token. Use `POST /cdn/download` to proxy the file. Any authenticated token can call this route: the team id in the URL must match the token's team. Empower READ is not required.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelistoverlay
POST/cdn/downloadDownload a private CDN file · Download a CDN file#
Ask an LLM
“How do I download a transcription from the Ringover CDN?”
“Can I fetch a private audio or video file through the public API?”
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. By signing up you are subscribing to the APIs.io and API Evangelist
newsletters — you can unsubscribe from any issue. See our
Privacy Policy and Terms.
openapi: 3.2.0
info:
license:
name: Proprietary – Contact us for usage terms
url: https://www.ringover.com/contact
description: '# Ringover Public API
Welcome to the Ringover Public API. This RESTful API lets you integrate Ringover telephony, messaging, contacts, and AI analytics into your applications. ## Base URL
| Region | Base URL |
|--------|----------|
| Europe | `https://public-api.ringover.com/v2` |
| United States | `https://public-api-us.ringover.com/v2` |
## Authentication
All requests must include your API key in the `Authorization` header:
```
Authorization: your-api-key-here
```
To create an API key:
1. Open the Ringover Dashboard. 2. Navigate to **Developer > API Keys**. 3. Click **Create an API key**, select a user, and set a label. 4. Configure the permissions for this key (see Permissions below). ## Permissions
Each API key is associated with **7 permission categories**, each configurable as **None**, **Read**, **Write**, or **Read+Write**:
| Category | Controls access to |
|----------|-------------------|
| **Calls** | Call history, archives, live call controls, callbacks |
| **Contacts** | Contact CRUD and phone number management |
| **Users** | User listing, plannings, presences, groups, user blacklists |
| **Numbers** | Phone number listing, team blacklist |
| **IVRs** | IVR/scenario listing, tag management |
| **Conversations** | SMS/Chat conversations, messages, SMS sending |
| **Empower** | AI call analysis, summaries, moments, analytics |
### The Monitoring flag (Supervision)
In addition to R/W permissions, each API key has a **Monitoring** toggle that controls the **scope** of data returned:
| Monitoring | Effect |
|------------|--------|
| **OFF** | Your permissions give access to **your own data only** (your calls, your numbers, your conversations…) |
| **ON** | Your permissions give access to **the entire team''s data** (all users, all calls, all conversations…) |
Monitoring does **not** grant additional permissions — it widens the scope of existing ones. Some routes **require** Monitoring to be enabled and will return `401` without it. Conversely, some routes may ignore the Monitoring flag entirely or apply it differently — unless stated otherwise in the endpoint documentation, the default behavior described above applies. > Each endpoint in this documentation specifies its exact permission and monitoring requirements. ### Special cases
- **Campaigns, Tasks, WhatsApp**: These routes do not require specific token permissions. A valid API key is sufficient. - **Empower**: Uses its own role system (Admin / Supervisor / User) in addition to the Empower R/W permission. - **Transcriptions**: Access is controlled by a team-level setting, not by the token permissions. - **Conferences**: All conference routes require Monitoring enabled. ## Rate Limiting
A **2-request-per-second** rate limit is applied per API key. Exceeding this limit returns `429 Too Many Requests`. ## Pagination
List endpoints support offset-based pagination with two parameters:
- `limit_count`: Maximum number of items to return (default: 100, max varies by endpoint). - `limit_offset`: Number of items to skip (default: 0). Some call-related endpoints also support cursor-based pagination via `last_id_returned`. ## Error Responses
| HTTP Code | Meaning |
|-----------|---------|
| `400` | Bad request — invalid parameters or body |
| `401` | Unauthorized — invalid/expired API key, or access denied by permission/monitoring checks on most endpoints |
| `403` | Forbidden — authenticated request refused by specific endpoint logic (notably some Empower routes) or upstream forwarded services |
| `402` | Payment required — feature not available on your plan |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
## SCIM 2.0 Provisioning
Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) for automated user and group provisioning from your identity provider (Okta, Microsoft Entra ID, …). It reuses the **same API key** as the REST API (`Authorization` header).'
version: 2.1.0
title: Ringover Public Cdn API
x-logo:
url: https://webcdn.ringover.com/app/img/misc/logo_app_redoc.png
backgroundColor: '#FAFAFA'
altText: Ringover Logo
termsOfService: https://ringover.com/terms/
contact:
email: support@ringover.com
servers:
- url: https://public-api.ringover.com/v2
description: Production server (Europe)
- url: https://public-api-us.ringover.com/v2
description: Production server (United States)
security:
- Authorization: []
tags:
- name: CDN
description: 'Private CDN URLs (`transcription_url`, `recap_url`, `audio_url`, `video_url`, and other Ringover CDN download links) cannot be opened with a public API token.
Use `POST /cdn/download` to proxy the file. Any authenticated token can call this route: the team id in the URL must match the token''s team. Empower READ is not required.'
paths:
/cdn/download:
post:
operationId: downloadCDNFile
tags:
- CDN
x-permissions:
required: none
monitoring: none
summary: Download a CDN file
description: 'Proxies a Ringover CDN download (transcription, recap, audio or video) using service credentials.
Private CDN URLs cannot be opened with a public API token or in a browser. Pass the full URL in the body of this route instead.
Typical sources:
- `transcription_url`, `recap_url`, `audio_url` or `video_url` from `GET /empower/call/{callUUID}`
- any other Ringover CDN download URL that belongs to your team
The `url` must:
- use a Ringover CDN host (`cdn.ringover.com`, `cdn-eu.ringover.com` or `cdn-us.ringover.com`)
- be a download path (`/v2/private/download/` or `/v2/public/download/`)
- belong to the team of the API token (the team id in the path is checked)
- point to a JSON, audio or video file (`.json`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.wav`, `.m4a`, `.webm`, `.ogg`, `.mov`, `.aac`)
Public download URLs (`/v2/public/download/`) are rewritten to the matching private path before the file is fetched.
The response is streamed. JSON is returned as JSON; audio and video are returned as the original binary, with the CDN `Content-Type` and `Content-Length` when present.
**Permission:** No specific permission required. A valid API key is sufficient. Empower Read is not required.
**Monitoring:** No impact. The team id in the URL must match the token''s team.
```
curl -X POST https://public-api.ringover.com/v2/cdn/download \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d ''{"url":"https://cdn.ringover.com/v2/private/download/teams/12345678/types/records/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.mp3"}'' \
-o recording.mp3
```'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
format: uri
minLength: 1
description: Full CDN download URL (transcription, recap, audio or video).
example: https://cdn.ringover.com/v2/private/download/teams/12345678/types/transcriptions/transcript/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.json
examples:
transcription:
summary: Transcription JSON
value:
url: https://cdn.ringover.com/v2/private/download/teams/12345678/types/transcriptions/transcript/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.json
recap:
summary: Recap JSON
value:
url: https://cdn-eu.ringover.com/v2/private/download/teams/12345678/types/transcriptions/aftercall/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.json
audio:
summary: Call recording
value:
url: https://cdn.ringover.com/v2/private/download/teams/12345678/types/records/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.mp3
video:
summary: Call video
value:
url: https://cdn.ringover.com/v2/private/download/teams/12345678/types/records/12345678-11111111/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee.mp4
responses:
'200':
description: File content, streamed from the CDN. Content-Type matches the file (JSON, audio or video).
content:
application/json:
schema:
type: object
additionalProperties: true
audio/mpeg:
schema:
type: string
format: binary
video/mp4:
schema:
type: string
format: binary
application/octet-stream:
schema:
type: string
format: binary
'400':
description: Bad request — invalid body, host, path or file type (only JSON, audio and video on an allowlisted Ringover CDN host).
'401':
description: Unauthorized — missing or invalid token.
'403':
description: Forbidden — the URL does not belong to the authenticated team (`url does not belong to your team`).
'404':
description: Not found — file not found on the CDN.
'502':
description: Bad gateway — failed to download the file from the CDN.
components:
securitySchemes:
Authorization:
description: "We use API keys for authentication to authorize API requests. First, you need to create a public access token (API key) and select the appropriate rights for each user. To do so:\n 1. Open the Ringover Dashboard.\n 2. Go to the **Developer** section.\n 3. Click the **Create an API key** button.\n 4. Select a user in the drop-down menu and enter a label for the key and click the **Create** button.\n 5. Click the **Edit** button corresponding to the API key and select the appropriate rights.\n\nOnce you've created a public access token, you can use it in the `Authorization` header to authenticate your HTTP request.\n\n```\nAuthorization: <your-public-token>\n```\n\nThis is the **recommended authentication method** and the only one supported by the REST and SCIM endpoints.\n"
type: apiKey
name: Authorization
in: header
AuthorizationQuery:
description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp`).**
Pass your Public API token via the `token` query string parameter:
```
POST /mcp?token=<your-public-token>
```
Useful for clients (no-code platforms, browser tools, etc.) that cannot set custom HTTP headers.
See the **mcp** tag for details on the three accepted authentication sources and their precedence.
'
type: apiKey
name: token
in: query
AuthorizationPath:
description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp/{token}`).**
Pass your Public API token directly inside the URL path:
```
POST /mcp/<your-public-token>
```
Most permissive variant — works with any HTTP client, including those that strip custom headers and query strings.
> ⚠️ The token appears in URLs and is therefore likely to be logged by proxies, browsers and access logs. Prefer the `Authorization` header whenever your client supports it, and rotate any token that may have leaked.
OpenAPI 3.0 does not support `apiKey` in `path`, so this scheme is declared in `query` for tooling compatibility — the actual transport is the URL path. See the **mcp** tag for details.
'
type: apiKey
name: token
in: query
x-tagGroups:
- name: Ringover Public API
tags:
- How to paginate?
- teams
- groups
- users
- numbers
- ivrs
- tags
- conferences
- calls
- campaigns
- channels
- contacts
- conversations
- messages
- sms
- profiles
- presences
- blacklist
- webhook
- callbacks
- surveys
- snoozes
- transcriptions
- cdn
- empower
- whatsapp
- task
- mcp
- name: SCIM 2.0 Provisioning
tags:
- scim