{
  "openapi": "3.1.0",
  "info": {
    "title": "OxgelAPI",
    "version": "1.0.0",
    "description": "Virtual phone numbers, OTP/SMS verification, bulk SMS and SMM APIs. 200+ countries, 1000+ services (WhatsApp, Telegram, Google, Facebook, OpenAI, Discord, etc.). Pay-as-you-go in USD.",
    "contact": { "name": "OxgelAPI", "url": "https://oxgelapi.com", "email": "support@oxgelapi.com" }
  },
  "servers": [{ "url": "https://oxgelapi.com/api/v1" }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Get your key at https://oxgelapi.com/dashboard/api-keys (format: OXGL-xxxx)" }
    }
  },
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/balance": {
      "get": {
        "summary": "Get wallet balance",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "balance": 12.45, "escrow": 0.85, "currency": "USD" } } } } }
      }
    },
    "/services": {
      "get": {
        "summary": "List supported services",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": [{ "code": "wa", "name": "WhatsApp" }, { "code": "tg", "name": "Telegram" }] } } } }
      }
    },
    "/countries": {
      "get": {
        "summary": "List supported countries",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": [{ "code": "187", "iso2": "US", "name": "USA" }] } } } }
      }
    },
    "/prices": {
      "get": {
        "summary": "Get current prices and stock for a service",
        "parameters": [
          { "name": "service", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": [{ "country": "187", "price": 0.18, "stock": 4 }] } } } }
      }
    },
    "/numbers/buy": {
      "post": {
        "summary": "Rent a virtual number",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object", "required": ["service", "country"],
            "properties": {
              "service": { "type": "string", "example": "wa" },
              "country": { "type": "string", "example": "187" },
              "operator": { "type": "string", "default": "any" }
            }
          } } }
        },
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": {
          "id": "5e8b...uuid", "order_code": "ORD-LX9F2A",
          "phone": "+15551234567", "expires_at": "2026-06-03T14:23:00.000Z", "cost": 0.18
        } } } } }
      }
    },
    "/numbers/status": {
      "get": {
        "summary": "Poll for incoming SMS",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "status": "received", "sms_code": "482913", "phone": "+15551234567" } } } } }
      }
    },
    "/numbers/cancel": {
      "post": {
        "summary": "Cancel a waiting order (allowed after 2 minutes)",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "ok": true, "refunded": 0.18 } } } } }
      }
    },
    "/numbers/finish": {
      "post": {
        "summary": "Mark order complete",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "ok": true } } } } }
      }
    },
    "/numbers/another": {
      "post": {
        "summary": "Request another SMS to the same number",
        "parameters": [{ "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "ok": true } } } } }
      }
    }
  }
}