{
  "openapi": "3.0.3",
  "info": {
    "title": "Umney Connect Business Calling Voice API",
    "version": "1.0.0",
    "description": "Public read API for Business Calling (voice:read). Docs: https://umneyconnect.com/developers/business-calling"
  },
  "servers": [
    { "url": "https://umneyconnect.com/api", "description": "Production" },
    { "url": "https://www.staging.umneyconnect.com/api", "description": "Staging" }
  ],
  "tags": [{ "name": "Calls" }, { "name": "Usage" }],
  "components": {
    "securitySchemes": {
      "ApiKeyBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "umk_live_voice_…",
        "description": "Business Calling token from Dashboard → Developers"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "parameters": {
      "CallId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "Call": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "fromId": { "type": "string" },
          "toId": { "type": "string" },
          "direction": { "type": "string", "enum": ["inbound", "outbound"] },
          "durationSecs": { "type": "number" },
          "result": { "type": "string" },
          "startedAt": { "type": "string" },
          "endedAt": { "type": "string", "nullable": true },
          "callSid": { "type": "string", "nullable": true },
          "mosScore": { "type": "number", "nullable": true }
        }
      },
      "VoiceUsage": {
        "type": "object",
        "properties": {
          "minutesTodayUtc": { "type": "number" },
          "callsStartedTodayUtc": { "type": "integer" },
          "inboundOffered7d": { "type": "integer" },
          "inboundAnswered7d": { "type": "integer" },
          "inboundAnswerRate7dPercent": { "type": "number", "nullable": true }
        }
      }
    }
  },
  "security": [{ "ApiKeyBearer": [] }, { "ApiKeyHeader": [] }],
  "paths": {
    "/v1/voice/calls": {
      "get": {
        "tags": ["Calls"],
        "summary": "List call records",
        "operationId": "listVoiceCalls",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          {
            "name": "direction",
            "in": "query",
            "schema": { "type": "string", "enum": ["inbound", "outbound"] }
          },
          { "name": "result", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Call list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Call" }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "limit": { "type": "integer" },
                        "nextCursor": { "type": "string", "nullable": true }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/voice/calls/{id}": {
      "get": {
        "tags": ["Calls"],
        "summary": "Get a call record",
        "operationId": "getVoiceCall",
        "parameters": [{ "$ref": "#/components/parameters/CallId" }],
        "responses": {
          "200": {
            "description": "Call",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Call" }
              }
            }
          }
        }
      }
    },
    "/v1/voice/usage": {
      "get": {
        "tags": ["Usage"],
        "summary": "Calling usage summary",
        "operationId": "getVoiceUsage",
        "responses": {
          "200": {
            "description": "Usage",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VoiceUsage" }
              }
            }
          }
        }
      }
    }
  }
}