openapi: 3.2.0
info:
  title: Numbers Online Phone Intelligence MCP API
  description: Phone number parsing, validation, and inbound caller-intelligence as a supplementary signal.
  version: 1.0.0
  contact:
    name: Phone Numbers Online
    url: https://numbers.online
servers:
- url: https://numbers.online
  description: Production server
- url: http://localhost:3000
  description: Development server
tags:
- name: MCP
  description: 'Model Context Protocol server for AI voice agents (Vapi, Retell, Pipecat, LiveKit): read-only phone-intelligence tools over Streamable HTTP'
paths:
  /api/v1/mcp:
    post:
      tags:
      - MCP
      summary: MCP server (Streamable HTTP, JSON-RPC 2.0)
      description: 'Model Context Protocol endpoint for AI voice agents. Stateless, read-only. Speaks JSON-RPC 2.0 — initialize / notifications/initialized / ping / tools/list / tools/call. Tools: phone_lookup, line_type, caller_risk, dnc_check, reassigned_check (all annotated readOnlyHint). dnc_check and reassigned_check are preview tools that return "unknown" (and are unbilled) until a licensed data partner is configured. Register it in Vapi as an MCP tool with metadata.protocol="shttp"; Retell/Pipecat/LiveKit can also call it. tools/call requires a key with the "mcp" use case (Authorization: Bearer); initialize/ping/tools/list are public discovery. Each billable tool call meters the bundled mcp_call rate ($0.015); all output is a supplementary, low-confidence signal — the agent keeps every routing and dialing decision. This endpoint is response-only (no server-initiated SSE): GET returns 405.'
      operationId: mcpRpc
      security:
      - BearerAuth: []
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                id:
                  description: Request id (omit for notifications).
                method:
                  type: string
                  example: tools/call
                params:
                  type: object
                  example:
                    name: phone_lookup
                    arguments:
                      number: '+14155552671'
      responses:
        '200':
          description: JSON-RPC response (result, or a tools/call result envelope).
        '202':
          description: Accepted notification (no body).
        '400':
          description: Parse error / invalid request / unsupported MCP-Protocol-Version.
        '401':
          description: tools/call without a valid "mcp"-scoped key.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
          description: Legacy field emitted ONLY by the pre-v1 parse family (/api/parse, /api/parse/bulk, /api/countries). /v1 routes return only `error` — do not depend on `success` there.
        error:
          type: string
          description: Human-readable error message (prose — switch on `code`, not on this string).
        code:
          type: string
          enum:
          - missing_key
          - invalid_key
          - use_case_forbidden
          - rate_limited_key
          - rate_limited_pool
          - rate_limited_ip
          - signature_invalid
          - insufficient_balance
          - account_suspended
          - paid_verification_required
          - receipt_invalid
          description: 'Stable machine-readable error code (added 2026-06-12, additive — older errors may omit it). See the "Error codes" section in the API description for the full table. A valid key on the wrong use case returns 403 use_case_forbidden (not 401): re-authing will not fix a permissions problem.'
        retry_after_seconds:
          type: integer
          description: 'Present on 429s: seconds until the window resets (mirrors the Retry-After header).'
      required:
      - error
  responses:
    RateLimited:
      description: Per-key rate limit exceeded. Retry after the number of seconds in the Retry-After header.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication
    CidQueryKeyAuth:
      type: apiKey
      in: query
      name: key
      description: API key in the `?key=` query param. Accepted by the header-less PBX endpoint GET /api/v1/cid/{number} and by the webhook adapters POST /api/v1/integrations/retell/inbound, POST /api/v1/integrations/vapi/tool, and POST /api/v1/sbc/redirect, whose upstream platforms set only a static webhook URL and cannot send an Authorization/X-API-Key header. The key can leak into access logs — use a dedicated, rotated key, and prefer header auth wherever the client supports it.