openapi: 3.2.0
info:
  title: Numbers Online Phone Intelligence System 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: System
  description: Operational endpoints (health checks)
paths:
  /api/health:
    get:
      tags:
      - System
      summary: Health check
      description: Liveness/readiness probe used by the container orchestrator and load balancer. NO AUTH REQUIRED. Returns 200 with a small status body when the service is up.
      operationId: healthCheck
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  db:
                    type: string
                    enum:
                    - up
                    - down
                    example: up
                  version:
                    type: string
                    example: v1.0.0
                  time:
                    type: string
                    format: date-time
        '503':
          description: Service degraded (database unreachable)
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: degraded
                  db:
                    type: string
                    example: down
                  version:
                    type: string
                  time:
                    type: string
                    format: date-time
components:
  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.