Ringover MCP API

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 MCP 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: MCP
  description: '## Model Context Protocol


    The MCP endpoint exposes a **curated** set of Ringover operations to AI assistants (Claude, ChatGPT, Cursor, etc.) via the Model Context Protocol. It is not a 1:1 copy of the REST API: tools that are hard for an agent to fill, rarely useful, or unsafe are omitted, and related mutations are grouped (for example `calls.archive`, `channels.control`, `users.update`). Source of truth for names, argument schemas and titles is `tools/list`. This page lists the frozen catalogue. ### Useful links


    - Model Context Protocol specification

    - Lifecycle & initialization

    - Tools

    - Streamable HTTP transport


    ### How it works


    MCP is JSON-RPC 2.0 over HTTP using the Streamable HTTP transport. All interactions use `POST /mcp` with a JSON-RPC body. The server is **stateless** — every request is independent. There is no session (`Mcp-Session-Id` is not used) and no `notifications/tools/list_changed`. ### Request headers


    Every `POST` must send:


    - `Content-Type: application/json`

    - `Accept: application/json, text/event-stream` — **both** media types are required (comma-separated, as MCP clients do). A request that omits `text/event-stream` is rejected with HTTP `400`. ### Response format


    Successful MCP calls return HTTP `200` with `Content-Type: application/json` and a **single JSON-RPC object** in the body. There is no SSE stream: the endpoint is stateless (one request, one response, no shared connection across tool calls), so Server-Sent Events would not add multiplexing here. ### JSON-RPC errors vs HTTP errors


    - **Supported methods** (`initialize`, `tools/list`, `tools/call`): invalid tool arguments, tool rate limits, and application failures on `tools/call` are returned with HTTP `200` (JSON-RPC `error` or a tool result with `isError: true`). - **HTTP transport rejections** (before the message is handled as MCP): invalid `Accept`, malformed JSON-RPC, unsupported method **name** (anything other than the three methods above), etc. → HTTP **`400`** with a **plain-text** body, not a JSON-RPC envelope. Example: `JSON RPC not handled: "monitor/unknown_method" unsupported`. - Missing or invalid credential → **`401`**. HTTP rate limit → **`429`**. ### Available JSON-RPC methods


    | Method | Purpose |

    |--------|---------|

    | `initialize` | Capability negotiation. Returns server info (`name: "ringover-public-api"`, `version: "v1.0.0"`) and capabilities. Optional — you can call `tools/list` or `tools/call` directly. |

    | `tools/list` | Returns the tools **this credential can use**, with `name`, `title`, `description`, `inputSchema` and `annotations`. |

    | `tools/call` | Execute a tool by `name` with `arguments`. |


    `tools/list` never returns a tool the caller cannot invoke. A write tool is listed only when the credential has the matching **write** grant. Calling a hidden name is refused (`forbidden`). ### Authentication


    The MCP endpoint accepts the same credentials as the rest of public-api:


    - a **Public API key** (raw, no `Bearer` prefix)

    - an **OAuth 2.0 access token** (`Authorization: Bearer `), when OAuth is enabled for the environment


    For API keys, three sources are tried in this **order** (first one set wins):


    | # | Source | Endpoint | Example | When to use |

    |---|--------|----------|---------|-------------|

    | 1 | URL path parameter | `POST /mcp/{token}` | `POST /mcp/abcd1234…` | Last resort for clients that cannot set headers or query strings. |

    | 2 | Query string `?token=` | `POST /mcp?token=…` | `POST /mcp?token=abcd1234…` | No-code / web tools that cannot set custom headers. |

    | 3 | `Authorization` header | `POST /mcp` | `Authorization: abcd1234…` | **Recommended** — same as REST. |


    The token is then normalized internally, so rate limiting, logging and permission checks behave the same regardless of source. > ⚠️ **Security note** — Tokens in the URL path or query string often appear in proxy logs, browser history and access logs. Prefer the `Authorization` header.'
paths:
  /mcp:
    post:
      operationId: mcpEndpoint
      tags:
      - MCP
      summary: Model Context Protocol (MCP) endpoint
      description: 'JSON-RPC 2.0 endpoint implementing the Model Context Protocol.

        The server is **stateless** — each request is independent, no session management.


        Supported methods: `initialize`, `tools/list`, `tools/call`.

        The tool catalogue is **curated** (read and write). `tools/list` returns only the tools this credential can call. Names use `{resource}.{action}` (for example `contacts.search`).


        ### Authentication


        Three accepted sources (first one set wins):


        1. URL path parameter — `POST /mcp/{token}` (see the dedicated operation below)

        2. Query string — `POST /mcp?token=…`

        3. `Authorization` header — `POST /mcp` (recommended)


        See the **mcp** tag description for transport headers (`Accept`), JSON responses, HTTP `400` transport errors, the tool catalogue, parameters, and permission requirements.'
      x-permissions:
        required: Depends on the tool called (see mcp tag description)
      security:
      - Authorization: []
      - AuthorizationQuery: []
      parameters:
      - name: Accept
        in: header
        required: true
        description: 'Must include **both** `application/json` and `text/event-stream` (comma-separated).

          Example: `application/json, text/event-stream`.

          '
        schema:
          type: string
          example: application/json, text/event-stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
            examples:
              initialize:
                summary: Initialize (optional in stateless mode)
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: initialize
                  params:
                    protocolVersion: '2025-06-18'
                    capabilities: {}
                    clientInfo:
                      name: my-client
                      version: 1.0.0
              tools_list:
                summary: List available tools
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/list
              tools_call:
                summary: Call a tool
                value:
                  jsonrpc: '2.0'
                  id: 3
                  method: tools/call
                  params:
                    name: contacts.search
                    arguments:
                      query: John
                      limit: 10
      responses:
        '200':
          description: 'JSON-RPC response (`Content-Type: application/json`). On success, the `result` field contains the method output.


            For supported methods, protocol and tool errors use HTTP `200`: JSON-RPC `error` (for example tool rate limit) or a `tools/call` result with `isError: true` (forbidden, not found, invalid input). Unknown method names and other transport-level failures are **not** included here — they return HTTP `400` (see below).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
              examples:
                tools_list_response:
                  summary: tools/list response (truncated)
                  value:
                    jsonrpc: '2.0'
                    id: 2
                    result:
                      tools:
                      - name: contacts.search
                        description: Search contacts by name, phone number, or company.
                        inputSchema:
                          type: object
                          properties:
                            query:
                              type: string
                              description: Search by name, phone number, or company
                            limit:
                              type: integer
                              description: Max results to return (1-500, default 50)
                tools_call_response:
                  summary: tools/call response
                  value:
                    jsonrpc: '2.0'
                    id: 3
                    result:
                      content:
                      - type: text
                        text: '{"contact_id": 123, "firstname": "John", "lastname": "Doe"}'
                error_response:
                  summary: JSON-RPC error (e.g. rate limit exceeded)
                  value:
                    jsonrpc: '2.0'
                    id: 3
                    error:
                      code: -32603
                      message: rate limit exceeded for tool contacts.search
        '400':
          description: 'HTTP transport rejection before MCP handles the message: invalid or incomplete `Accept` header,

            malformed JSON-RPC, unsupported method name (only `initialize`, `tools/list`, and `tools/call` are supported),

            or similar. The body is **plain text**, not JSON-RPC (for example `JSON RPC not handled: "foo" unsupported`).

            '
        '401':
          description: Missing or invalid API key.
        '429':
          description: HTTP rate limit exceeded (1 req/s per API key, burst 10).
  /mcp/{token}:
    post:
      operationId: mcpEndpointWithToken
      tags:
      - MCP
      summary: Model Context Protocol (MCP) endpoint — token in URL path
      description: 'Same JSON-RPC 2.0 endpoint as `POST /mcp`, but the Public API token is supplied **as a path parameter** instead of through the `Authorization` header or the `?token=` query string.


        This variant exists because some MCP clients cannot set custom HTTP headers nor query strings. Behavior is otherwise **strictly identical** to `POST /mcp`:


        - same JSON-RPC methods (`initialize`, `tools/list`, `tools/call`)

        - same Streamable HTTP transport (`Accept`, JSON responses, HTTP `400` transport errors — see the **mcp** tag)

        - same rate limiting (1 req/s per token, burst 10)

        - same permission and Monitoring rules

        - same stateless behavior (no `Mcp-Session-Id`)


        > ⚠️ **Security note** — The token is part of the URL and will likely be logged by proxies, browsers and access logs. Use this variant only when neither the `Authorization` header nor the `?token=` query string is available, and rotate any token that may have leaked.


        OpenAPI 3.0 cannot declare an `apiKey` security scheme located in `path`, so this operation is documented with the `AuthorizationPath` scheme (declared as `query` for tooling compatibility — the actual transport is the URL path shown by the `token` path parameter below).'
      x-permissions:
        required: Depends on the tool called (see mcp tag description)
      security:
      - AuthorizationPath: []
      parameters:
      - name: token
        in: path
        required: true
        description: Your Public API token (same value as the `Authorization` header).
        schema:
          type: string
          example: your-public-token
      - name: Accept
        in: header
        required: true
        description: 'Must include **both** `application/json` and `text/event-stream` (comma-separated).

          Example: `application/json, text/event-stream`.

          '
        schema:
          type: string
          example: application/json, text/event-stream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: 'JSON-RPC response (`Content-Type: application/json`). Same as `POST /mcp`.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '400':
          description: HTTP transport rejection (invalid `Accept`, unsupported method name, malformed JSON-RPC, etc.). Plain-text body — see `POST /mcp`.
        '401':
          description: Missing or invalid API key.
        '429':
          description: HTTP rate limit exceeded (1 req/s per API key, burst 10).
components:
  schemas:
    JsonRpcError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          description: 'JSON-RPC error code. Standard codes: -32700 (parse error), -32600 (invalid request), -32601 (method not found), -32602 (invalid params), -32603 (internal error).'
        message:
          type: string
          description: Human-readable error message.
        data:
          description: Optional additional error data.
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: integer
          - type: 'null'
          description: Echoed request identifier, or null for notifications.
        result:
          type: object
          description: Present on success. Content depends on the method called.
        error:
          $ref: '#/components/schemas/JsonRpcError'
    JsonRpcRequest:
      type: object
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
          description: JSON-RPC protocol version. Must be "2.0".
        id:
          oneOf:
          - type: string
          - type: integer
          description: Request identifier. The server echoes it back in the response.
        method:
          type: string
          description: 'The JSON-RPC method to call: `initialize`, `tools/list`, or `tools/call`.'
          enum:
          - initialize
          - tools/list
          - tools/call
        params:
          type: object
          description: Method-specific parameters. Required for `initialize` and `tools/call`, optional for `tools/list`.
  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