{
  "openapi": "3.1.0",
  "info": {
    "title": "DIDHub API",
    "version": "0.1.0",
    "description": "REST API for virtual phone numbers, SIP trunks, calls, SMS, and webhooks. This is a placeholder spec — it will be replaced by the auto-generated spec from the Worker's `@hono/zod-openapi` routes once that wiring lands.",
    "contact": {
      "name": "DIDHub support",
      "email": "support@didhub.io",
      "url": "https://didhub.io"
    },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://api.didhub.io/v1", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key (Bearer)"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string", "example": "unauthorized" },
          "message": { "type": "string", "example": "Missing or invalid API key" },
          "request_id": { "type": "string", "example": "req_a4f9c2b1" }
        }
      }
    }
  },
  "paths": {
    "/numbers": {
      "get": {
        "summary": "List numbers",
        "description": "Return all DIDs on the calling account.",
        "tags": ["Numbers"],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "type": "object" } },
                    "next_cursor": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Buy a number",
        "description": "Purchase a DID in a given country / area / type. Self-serve in unregulated markets; for regulated markets the response includes `kyc_required: true` and the number stays in `pending` state until KYC clears.",
        "tags": ["Numbers"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["country", "type"],
                "properties": {
                  "country": { "type": "string", "example": "GB" },
                  "area": { "type": "string", "example": "20" },
                  "type": { "type": "string", "enum": ["geographic", "mobile", "toll_free", "national"] }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Number provisioned (or pending KYC)" },
          "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  }
}