{
  "components": {
    "schemas": {
      "Agent": {
        "properties": {
          "audio_stream_url": {
            "type": "string"
          },
          "begin_message": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "mode": {
            "enum": [
              "external_audio",
              "external_text",
              "hosted"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "recording_enabled": {
            "type": "boolean"
          },
          "system_prompt": {
            "type": "string"
          },
          "tools": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "voice": {
            "type": "string"
          },
          "webhook_url": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "mode"
        ],
        "type": "object"
      },
      "AgentEndpoint": {
        "properties": {
          "audio_stream_url": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "webhook_url": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "webhook_url",
          "audio_stream_url"
        ],
        "type": "object"
      },
      "BillingSettings": {
        "properties": {
          "auto_recharge_enabled": {
            "type": "boolean"
          },
          "organization_id": {
            "type": "string"
          },
          "payment_method_reference": {
            "type": "string"
          },
          "payment_provider": {
            "enum": [
              "stripe"
            ],
            "type": "string"
          },
          "recharge_amount_minor": {
            "type": "integer"
          },
          "threshold_minor": {
            "type": "integer"
          }
        },
        "required": [
          "organization_id"
        ],
        "type": "object"
      },
      "CallArtifactImport": {
        "properties": {
          "label": {
            "type": "string"
          },
          "mode": {
            "enum": [
              "auto",
              "folder_per_call",
              "file_per_call"
            ],
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "source_path": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "source_path"
        ],
        "type": "object"
      },
      "CreateOrganization": {
        "properties": {
          "name": {
            "type": "string"
          },
          "project_name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CustomerOnboarding": {
        "properties": {
          "acceptable_use_attested": {
            "type": "boolean"
          },
          "anticipated_usage": {
            "enum": [
              "business",
              "wholesale",
              "unknown"
            ],
            "type": "string"
          },
          "business_country": {
            "type": "string"
          },
          "business_name": {
            "type": "string"
          },
          "business_website": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "service_usage_description": {
            "type": "string"
          },
          "target_regions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "organization_id",
          "business_name",
          "anticipated_usage",
          "service_usage_description"
        ],
        "type": "object"
      },
      "DashboardBootstrap": {
        "properties": {
          "auth_provider": {
            "type": "string"
          },
          "auth_subject": {
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organization_name": {
            "type": "string"
          },
          "project_name": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "type": "object"
      },
      "GatewayDeployment": {
        "properties": {
          "carrier_account_id": {
            "type": "string"
          },
          "deployment_model_id": {
            "enum": [
              "fully_managed_cloud",
              "managed_numbers_self_hosted_gateway"
            ],
            "type": "string"
          },
          "mode": {
            "enum": [
              "cloud_hosted",
              "self_hosted"
            ],
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "provider_account_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "project_id"
        ],
        "type": "object"
      },
      "GatewayHealthReport": {
        "properties": {
          "api_health": {
            "type": "object"
          },
          "asterisk_status": {
            "type": "object"
          },
          "checks": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "last_test_result": {
            "type": "object"
          },
          "media_health": {
            "type": "object"
          },
          "public_url": {
            "type": "string"
          },
          "secrets_redacted": {
            "type": "boolean"
          },
          "storage": {
            "type": "object"
          },
          "version": {
            "type": "string"
          },
          "voice_gateway_health": {
            "type": "object"
          }
        },
        "type": "object"
      },
      "InboundCallRoute": {
        "properties": {
          "from_phone_number": {
            "description": "Caller number when available.",
            "type": "string"
          },
          "live_media": {
            "description": "Explicitly request the live media worker path. Defaults to false.",
            "type": "boolean"
          },
          "provider": {
            "description": "Carrier/provider that delivered the call.",
            "type": "string"
          },
          "provider_call_id": {
            "description": "Carrier, DIDWW, or Asterisk call reference.",
            "type": "string"
          },
          "recording_enabled": {
            "type": "boolean"
          },
          "to_phone_number": {
            "description": "Called platform number assigned to an agent.",
            "type": "string"
          }
        },
        "required": [
          "to_phone_number"
        ],
        "type": "object"
      },
      "ManagedNumberAssignment": {
        "properties": {
          "carrier": {
            "description": "Plain alias for provider.",
            "type": "string"
          },
          "carrier_number_reference": {
            "description": "Plain alias for provider_number_id.",
            "type": "string"
          },
          "didww_verification_id": {
            "type": "string"
          },
          "internal_notes": {
            "type": "string"
          },
          "monthly_recurring_minor": {
            "type": "integer"
          },
          "phone_number": {
            "description": "Plain alias for e164. Can be omitted when portal/order evidence already stored an exact phone number.",
            "type": "string"
          },
          "provider_order_id": {
            "type": "string"
          },
          "regulatory_status": {
            "type": "string"
          },
          "reviewed_by": {
            "type": "string"
          },
          "setup_cost_minor": {
            "type": "integer"
          }
        },
        "required": [],
        "type": "object"
      },
      "ManagedNumberOrderPreview": {
        "oneOf": [
          {
            "required": [
              "available_number_cache_id"
            ]
          },
          {
            "required": [
              "available_did_id",
              "phone_number",
              "sku_id"
            ]
          }
        ],
        "properties": {
          "available_did_id": {
            "description": "DIDWW available_dids.id for the exact selected phone number.",
            "type": "string"
          },
          "available_number_cache_id": {
            "description": "Preferred OpenPhonex cache row id from GET /v1/provider/didww/available-number-cache. Hydrates available_did_id, phone_number, sku_id, did_group_id, and price snapshot.",
            "type": "string"
          },
          "available_provider_number_id": {
            "description": "Alias for available_did_id.",
            "type": "string"
          },
          "customer_first_charge_minor": {
            "description": "Optional operator-entered customer first charge override; defaults to managed-number pricing policy.",
            "type": "integer"
          },
          "monthly_recurring_minor": {
            "type": "integer"
          },
          "phone_number": {
            "description": "Exact E.164 number shown in DIDWW available_dids.",
            "type": "string"
          },
          "prepay_months": {
            "description": "Operator-entered first-billing cycle multiplier, e.g. 3 for quarterly prepay.",
            "type": "integer"
          },
          "price_snapshot": {
            "type": "object"
          },
          "provider_available_number_cache_id": {
            "description": "Alias for available_number_cache_id.",
            "type": "string"
          },
          "provider_order_total_minor": {
            "description": "Operator-entered exact first provider charge/order total from DIDWW order preview, portal confirmation, or owned-DID evidence. Required before quote_summary.is_final can become true.",
            "type": "integer"
          },
          "registration_cost_minor": {
            "type": "integer"
          },
          "reviewed_by": {
            "type": "string"
          },
          "routing_config": {
            "description": "Intended voice/SMS trunk or Number rules mapping after order completion.",
            "type": "object"
          },
          "setup_cost_minor": {
            "type": "integer"
          },
          "sku_id": {
            "description": "DIDWW SKU used in Create Order.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ManagedNumberPortalOrderEvidence": {
        "properties": {
          "evidence_reference": {
            "description": "Screenshot key, portal note, or internal reference; do not include secrets.",
            "type": "string"
          },
          "identity_id": {
            "type": "string"
          },
          "identity_name": {
            "description": "DIDWW end-user identity used, e.g. Herous Futurus OU.",
            "type": "string"
          },
          "internal_notes": {
            "type": "string"
          },
          "monthly_recurring_minor": {
            "type": "integer"
          },
          "phone_number": {
            "description": "Exact E.164 number confirmed in the DIDWW portal.",
            "type": "string"
          },
          "prepay_months": {
            "description": "First-billing cycle multiplier, e.g. 3 for quarterly prepay.",
            "type": "integer"
          },
          "provider_number_id": {
            "description": "DIDWW DID/reference after portal purchase or selection.",
            "type": "string"
          },
          "provider_order_id": {
            "description": "DIDWW portal order id/reference when available.",
            "type": "string"
          },
          "provider_order_total_minor": {
            "description": "Exact DIDWW portal first charge/order total in minor units.",
            "type": "integer"
          },
          "registration_cost_minor": {
            "type": "integer"
          },
          "reviewed_by": {
            "type": "string"
          },
          "setup_cost_minor": {
            "type": "integer"
          }
        },
        "required": [
          "phone_number"
        ],
        "type": "object"
      },
      "ManagedNumberRequest": {
        "properties": {
          "agent_endpoint_id": {
            "description": "Backwards-compatible alias for external audio agents.",
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "carrier": {
            "description": "Plain alias for provider. Default: didww.",
            "type": "string"
          },
          "country": {
            "description": "ISO country code or country name.",
            "type": "string"
          },
          "customer_reference": {
            "type": "string"
          },
          "customer_type": {
            "description": "business, individual, agent_builder, or internal.",
            "type": "string"
          },
          "number_type": {
            "description": "local, national, mobile, toll_free, shared_cost, or UIFN.",
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "preferred_phone_number": {
            "description": "Optional customer preference. Until DIDWW enables available_dids search, this does not reserve or promise a specific DID.",
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "requested_capabilities": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "country"
        ],
        "type": "object"
      },
      "NumberRules": {
        "properties": {
          "incoming": {
            "properties": {
              "agent_endpoint_id": {
                "type": "string"
              },
              "agent_id": {
                "type": "string"
              },
              "fallback": {
                "type": "object"
              },
              "phone_number": {
                "description": "Forward target when forwarding to another phone number.",
                "type": "string"
              },
              "phone_server_id": {
                "type": "string"
              },
              "when_called": {
                "enum": [
                  "answer_with_openphonex_agent",
                  "send_live_audio_to_my_app",
                  "send_to_my_phone_server",
                  "forward_to_phone_number",
                  "disabled"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "outgoing": {
            "properties": {
              "allowed_agents": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "allowed_countries": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "can_be_used_as_caller_id": {
                "type": "boolean"
              },
              "max_concurrent_calls": {
                "description": "0 means no explicit Number rule cap.",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "recording": {
            "properties": {
              "consent_state": {
                "type": "string"
              },
              "enabled": {
                "type": "boolean"
              },
              "retention_days": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "OutboundCall": {
        "properties": {
          "agent_endpoint_id": {
            "description": "Backwards-compatible alias.",
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "from_phone_number_id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "recipient_type": {
            "enum": [
              "business"
            ],
            "type": "string"
          },
          "to_phone_number": {
            "type": "string"
          },
          "user_authorization": {
            "type": "object"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "from_phone_number_id",
          "to_phone_number",
          "recipient_type",
          "country",
          "purpose"
        ],
        "type": "object"
      },
      "PhoneNumberRequest": {
        "properties": {
          "agent_endpoint_id": {
            "type": "string"
          },
          "available_provider_number_id": {
            "description": "Provider available-number identifier captured before ordering. For DIDWW this is available_dids.id.",
            "type": "string"
          },
          "carrier": {
            "description": "Plain alias for provider.",
            "type": "string"
          },
          "carrier_number_reference": {
            "description": "Plain alias for provider_number_id.",
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "monthly_recurring_minor": {
            "type": "integer"
          },
          "number_type": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "phone_number": {
            "description": "Plain alias for e164.",
            "type": "string"
          },
          "price_snapshot": {
            "description": "Captured quote used for audit/customer display; DIDWW API remains authoritative when quote is fetched.",
            "type": "object"
          },
          "project_id": {
            "type": "string"
          },
          "provider_order_id": {
            "description": "Provider order identifier returned after order execution.",
            "type": "string"
          },
          "setup_cost_minor": {
            "type": "integer"
          }
        },
        "required": [
          "organization_id",
          "project_id"
        ],
        "type": "object"
      },
      "PhoneServer": {
        "properties": {
          "allowed_sip_ips": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "auth_mode": {
            "enum": [
              "ip_allowlist",
              "sip_credentials",
              "ip_allowlist_and_credentials"
            ],
            "type": "string"
          },
          "metadata": {
            "type": "object"
          },
          "name": {
            "description": "Customer-facing label, e.g. My phone server.",
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "password_reference": {
            "description": "Reference to an external secret; plaintext passwords are not returned.",
            "type": "string"
          },
          "port": {
            "default": 5060,
            "type": "integer"
          },
          "project_id": {
            "type": "string"
          },
          "server_address": {
            "description": "Hostname or public IP of the customer's phone server.",
            "type": "string"
          },
          "transport": {
            "enum": [
              "udp",
              "tcp",
              "tls"
            ],
            "type": "string"
          },
          "username": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "server_address"
        ],
        "type": "object"
      },
      "ProviderAccount": {
        "properties": {
          "account_mode": {
            "enum": [
              "managed",
              "byo",
              "self_managed",
              "sandbox",
              "future_provider"
            ],
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RouteTrialCall": {
        "properties": {
          "from_phone_number": {
            "type": "string"
          },
          "live_media": {
            "description": "Explicitly request the live media worker path.",
            "type": "boolean"
          },
          "pin": {
            "type": "string"
          },
          "provider_call_id": {
            "type": "string"
          }
        },
        "required": [
          "pin"
        ],
        "type": "object"
      },
      "RunGatewayFees": {
        "properties": {
          "dry_run": {
            "type": "boolean"
          },
          "organization_id": {
            "type": "string"
          },
          "period": {
            "description": "Billing period in YYYY-MM format. Defaults to the current UTC month.",
            "pattern": "^\\d{4}-\\d{2}$",
            "type": "string"
          },
          "project_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id"
        ],
        "type": "object"
      },
      "RunNumberFees": {
        "properties": {
          "dry_run": {
            "type": "boolean"
          },
          "organization_id": {
            "type": "string"
          },
          "period": {
            "description": "Billing period in YYYY-MM format. Defaults to the current UTC month.",
            "pattern": "^\\d{4}-\\d{2}$",
            "type": "string"
          },
          "project_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id"
        ],
        "type": "object"
      },
      "SmsMessage": {
        "properties": {
          "body": {
            "type": "string"
          },
          "categories": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "from_phone_number_id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "recipient_type": {
            "enum": [
              "business"
            ],
            "type": "string"
          },
          "to_phone_number": {
            "type": "string"
          },
          "user_authorization": {
            "type": "object"
          }
        },
        "required": [
          "organization_id",
          "project_id",
          "from_phone_number_id",
          "to_phone_number",
          "body",
          "recipient_type",
          "purpose"
        ],
        "type": "object"
      },
      "Topup": {
        "properties": {
          "amount_cents": {
            "type": "integer"
          },
          "idempotency_key": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "amount_cents",
          "idempotency_key"
        ],
        "type": "object"
      },
      "TrialCall": {
        "properties": {
          "agent_endpoint_id": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "demo_phone_number": {
            "type": "string"
          },
          "max_free_seconds": {
            "type": "integer"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "project_id"
        ],
        "type": "object"
      },
      "WebCall": {
        "properties": {
          "agent_endpoint_id": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "browser_session_id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "project_id": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "recording_enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "organization_id",
          "project_id"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "ApiKeyBearer": {
        "description": "Scoped tai_ bearer keys are required by default for tenant/operator routes. Set OPENPHONEX_AUTH_MODE=development_open only for local demos.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Agent-native telephony API for customer onboarding, credits, numbers, webhooks, gateways, and policy-gated calls.",
    "title": "Telephony AI API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/mcp": {
      "post": {
        "responses": {
          "200": {
            "description": "MCP response"
          }
        },
        "summary": "Hosted MCP endpoint"
      }
    },
    "/metrics": {
      "get": {
        "responses": {
          "200": {
            "description": "Metrics text"
          }
        },
        "summary": "Read Prometheus-style operational metrics"
      }
    },
    "/v1/activation-state": {
      "get": {
        "responses": {
          "200": {
            "description": "Activation state"
          }
        },
        "summary": "Get live customer activation checklist and next action"
      }
    },
    "/v1/agent-endpoints": {
      "get": {
        "responses": {
          "200": {
            "description": "Agent endpoints"
          }
        },
        "summary": "List agent webhook/audio endpoints"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentEndpoint"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Agent endpoint"
          }
        },
        "summary": "Connect an agent"
      }
    },
    "/v1/agents": {
      "get": {
        "responses": {
          "200": {
            "description": "Agents"
          }
        },
        "summary": "List first-class agents"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Agent"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Agent"
          }
        },
        "summary": "Create an external or hosted agent"
      }
    },
    "/v1/agents/{agent_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Agent"
          }
        },
        "summary": "Get one agent"
      },
      "patch": {
        "responses": {
          "200": {
            "description": "Agent"
          }
        },
        "summary": "Update one agent"
      }
    },
    "/v1/agents/{agent_id}/handoff": {
      "get": {
        "responses": {
          "200": {
            "description": "Agent handoff"
          }
        },
        "summary": "Get generated agent setup handoff"
      }
    },
    "/v1/api-keys": {
      "get": {
        "responses": {
          "200": {
            "description": "API keys"
          }
        },
        "summary": "List scoped API keys"
      },
      "post": {
        "responses": {
          "201": {
            "description": "API key with one-time token"
          }
        },
        "summary": "Create a scoped API key"
      }
    },
    "/v1/api-keys/{key_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "API key"
          }
        },
        "summary": "Get one API key"
      }
    },
    "/v1/api-keys/{key_id}/revoke": {
      "post": {
        "responses": {
          "200": {
            "description": "Revoked API key"
          }
        },
        "summary": "Revoke an API key"
      }
    },
    "/v1/audit-events": {
      "get": {
        "responses": {
          "200": {
            "description": "Audit events"
          }
        },
        "summary": "List audit events"
      }
    },
    "/v1/backups": {
      "get": {
        "responses": {
          "200": {
            "description": "Backups"
          }
        },
        "summary": "List operational backups"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Backup"
          }
        },
        "summary": "Create a metadata/database backup"
      }
    },
    "/v1/billing/gateway-fees/run": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunGatewayFees"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Gateway billing run result with charged, already charged, dry-run, and blocked items"
          }
        },
        "summary": "Run idempotent recurring monthly hosted-gateway billing"
      }
    },
    "/v1/billing/number-fees/run": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunNumberFees"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Billing run result with charged, already charged, dry-run, and blocked items"
          }
        },
        "summary": "Run idempotent recurring monthly number-fee billing for active numbers"
      }
    },
    "/v1/billing/settings": {
      "get": {
        "responses": {
          "200": {
            "description": "Billing settings"
          }
        },
        "summary": "Read wallet billing settings and auto-recharge readiness"
      },
      "patch": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingSettings"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Billing settings"
          }
        },
        "summary": "Update safe auto-recharge settings without triggering a live charge"
      }
    },
    "/v1/billing/stripe/topup-sessions": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Topup"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Stripe checkout session or disabled status"
          }
        },
        "summary": "Create a Stripe checkout topup session when enabled"
      }
    },
    "/v1/billing/stripe/webhook": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Stripe webhook processing result"
          }
        },
        "summary": "Receive a signed Stripe checkout webhook and credit the wallet idempotently"
      }
    },
    "/v1/byo/didww/setup-checks": {
      "get": {
        "responses": {
          "200": {
            "description": "BYO DIDWW setup checks with provider_readiness"
          }
        },
        "summary": "Run secret-redacted BYO DIDWW setup checks, optionally with live safe reads"
      },
      "post": {
        "responses": {
          "200": {
            "description": "BYO DIDWW setup checks with provider_readiness"
          }
        },
        "summary": "Run BYO DIDWW setup checks with explicit operator/customer flags and optional live safe reads"
      }
    },
    "/v1/call-artifact-imports": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallArtifactImport"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Imported artifacts"
          }
        },
        "summary": "Import local call recordings and artifacts for demos"
      }
    },
    "/v1/calls": {
      "get": {
        "responses": {
          "200": {
            "description": "Calls"
          }
        },
        "summary": "List calls"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutboundCall"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Call"
          }
        },
        "summary": "Place a policy-gated outbound call"
      }
    },
    "/v1/calls/inbound/route": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InboundCallRoute"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Inbound call route result"
          }
        },
        "summary": "Route an inbound dedicated-number call to its assigned agent"
      }
    },
    "/v1/calls/{call_id}/artifacts": {
      "get": {
        "responses": {
          "200": {
            "description": "Artifacts"
          }
        },
        "summary": "List call artifacts"
      }
    },
    "/v1/calls/{call_id}/observability": {
      "get": {
        "responses": {
          "200": {
            "description": "Call observability bundle"
          }
        },
        "summary": "Get dashboard call observability bundle"
      }
    },
    "/v1/calls/{call_id}/recording": {
      "delete": {
        "responses": {
          "200": {
            "description": "Deleted recording"
          }
        },
        "summary": "Delete the active call recording metadata and audit the action"
      },
      "get": {
        "responses": {
          "200": {
            "description": "Recording"
          }
        },
        "summary": "Get call recording metadata and disclosure state"
      }
    },
    "/v1/calls/{call_id}/transcript": {
      "get": {
        "responses": {
          "200": {
            "description": "Transcript"
          }
        },
        "summary": "Get call transcript turns"
      }
    },
    "/v1/calls/{call_id}/transcript/stream": {
      "get": {
        "responses": {
          "200": {
            "description": "Transcript stream"
          }
        },
        "summary": "Get transcript stream events"
      }
    },
    "/v1/calls/{call_id}/waveform": {
      "get": {
        "responses": {
          "200": {
            "description": "Waveform"
          }
        },
        "summary": "Get waveform peaks for playback"
      }
    },
    "/v1/conversations": {
      "get": {
        "responses": {
          "200": {
            "description": "Conversations"
          }
        },
        "summary": "List SMS conversations"
      }
    },
    "/v1/conversations/{conversation_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Conversation"
          }
        },
        "summary": "Get one SMS conversation"
      }
    },
    "/v1/coverage-matrix": {
      "get": {
        "responses": {
          "200": {
            "description": "Coverage matrix"
          }
        },
        "summary": "List country coverage, messaging, simple onboarding terms, and safe activation speed"
      }
    },
    "/v1/customer-onboarding": {
      "get": {
        "responses": {
          "200": {
            "description": "Records"
          }
        },
        "summary": "List business onboarding records"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerOnboarding"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Onboarding record"
          }
        },
        "summary": "Submit business onboarding details"
      }
    },
    "/v1/customer-onboarding/{onboarding_id}/review": {
      "post": {
        "responses": {
          "200": {
            "description": "Onboarding record"
          }
        },
        "summary": "Update customer onboarding review status"
      }
    },
    "/v1/dashboard/bootstrap": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DashboardBootstrap"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Linked dashboard user, organization, project, membership, and session token"
          }
        },
        "summary": "Internal Auth.js-to-control-plane bootstrap for human dashboard sessions"
      }
    },
    "/v1/dashboard/me": {
      "get": {
        "responses": {
          "200": {
            "description": "Dashboard principal"
          }
        },
        "summary": "Read the current dashboard principal, workspace, project, membership, and wallet"
      }
    },
    "/v1/end-users/{end_user_profile_id}/registration-status": {
      "get": {
        "responses": {
          "200": {
            "description": "Registration status"
          }
        },
        "summary": "KYC + DIDWW identity + per-number registration status with derived customer status and '~48h, usually faster' headline"
      }
    },
    "/v1/end-users/{end_user_profile_id}/submit-registration": {
      "post": {
        "responses": {
          "201": {
            "description": "Per-step mutation request ids and per-number registration state"
          }
        },
        "summary": "Enqueue the DIDWW end-user registration mutation chain (identity/address/attach/verification) through the operator queue; identity is org-level and reused"
      }
    },
    "/v1/gateway-deployments": {
      "get": {
        "responses": {
          "200": {
            "description": "Gateways"
          }
        },
        "summary": "List media gateways"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GatewayDeployment"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Gateway"
          }
        },
        "summary": "Create a deployment"
      }
    },
    "/v1/gateway-deployments/{gateway_id}/health-report": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GatewayHealthReport"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated gateway deployment"
          }
        },
        "summary": "Report self-hosted gateway health, version, storage, and last test result"
      }
    },
    "/v1/health": {
      "get": {
        "responses": {
          "200": {
            "description": "Health report"
          }
        },
        "summary": "Read API, database, storage, provider, and worker readiness"
      }
    },
    "/v1/kyc/sessions": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "end_user_profile_id": {
                    "type": "string"
                  },
                  "expected_details": {
                    "type": "object"
                  },
                  "organization_id": {
                    "type": "string"
                  },
                  "profile_type": {
                    "enum": [
                      "individual",
                      "business"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "organization_id",
                  "profile_type"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Verification session with hosted didit URL; reused when one is already pending or approved"
          }
        },
        "summary": "Start a didit.me KYC (individual) or KYB (business) verification session for an end-user profile"
      }
    },
    "/v1/kyc/sessions/{end_user_profile_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "KYC session state"
          }
        },
        "summary": "Read KYC/KYB status and the extracted decision summary (no raw document URLs)"
      }
    },
    "/v1/messages": {
      "get": {
        "responses": {
          "200": {
            "description": "Messages"
          }
        },
        "summary": "List SMS messages"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsMessage"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Message"
          }
        },
        "summary": "Send a policy-gated outbound SMS"
      }
    },
    "/v1/messages/inbound/didww": {
      "get": {
        "responses": {
          "201": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW inbound SMS HTTP callback through query variables"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW inbound SMS HTTP callback"
      },
      "put": {
        "responses": {
          "201": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW inbound SMS HTTP callback"
      }
    },
    "/v1/messages/status/didww": {
      "get": {
        "responses": {
          "200": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW SMS delivery callback through query variables"
      },
      "post": {
        "responses": {
          "200": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW SMS delivery callback"
      },
      "put": {
        "responses": {
          "200": {
            "description": "Message"
          }
        },
        "summary": "Receive DIDWW SMS delivery callback"
      }
    },
    "/v1/messages/{message_id}/delivery-events": {
      "get": {
        "responses": {
          "200": {
            "description": "Delivery events"
          }
        },
        "summary": "List SMS provider delivery events for one message"
      }
    },
    "/v1/metrics": {
      "get": {
        "responses": {
          "200": {
            "description": "Metrics"
          }
        },
        "summary": "Read JSON operational metrics"
      }
    },
    "/v1/number-catalog": {
      "get": {
        "responses": {
          "200": {
            "description": "Number catalog"
          }
        },
        "summary": "Search the stored DIDWW number catalog with setup/monthly SKU snapshots, capabilities, and onboarding terms"
      }
    },
    "/v1/number-requests": {
      "get": {
        "responses": {
          "200": {
            "description": "Number requests"
          }
        },
        "summary": "List managed phone-number requests"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManagedNumberRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Number request"
          }
        },
        "summary": "Request a managed OpenPhonex phone number"
      }
    },
    "/v1/number-requests/{request_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Number request"
          }
        },
        "summary": "Get one managed phone-number request"
      },
      "patch": {
        "responses": {
          "200": {
            "description": "Number request"
          }
        },
        "summary": "Update managed phone-number request status or notes"
      }
    },
    "/v1/number-requests/{request_id}/assign": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManagedNumberAssignment"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Assigned number request"
          }
        },
        "summary": "Operator assigns an owned or ordered phone number to a request"
      }
    },
    "/v1/number-requests/{request_id}/portal-order-evidence": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManagedNumberPortalOrderEvidence"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Number request with portal order evidence"
          }
        },
        "summary": "Operator records DIDWW portal order evidence without creating a provider mutation"
      }
    },
    "/v1/number-requests/{request_id}/portal-order-evidence-report": {
      "get": {
        "responses": {
          "200": {
            "description": "Redacted portal evidence report"
          }
        },
        "summary": "Export redacted DIDWW portal evidence flags for SCH-181 readiness"
      }
    },
    "/v1/number-requests/{request_id}/provider-order-preview": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManagedNumberOrderPreview"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Number request with linked provider mutation preview"
          }
        },
        "summary": "Operator creates a linked DIDWW order dry-run after selecting an exact available_dids.id"
      }
    },
    "/v1/numbers": {
      "get": {
        "responses": {
          "200": {
            "description": "Phone numbers"
          }
        },
        "summary": "List phone numbers"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneNumberRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Phone number"
          }
        },
        "summary": "Operator/internal attach an owned carrier number or create a local fake number"
      }
    },
    "/v1/numbers/requirements": {
      "get": {
        "responses": {
          "200": {
            "description": "registration_required, field/document lists, activation estimate, conflict_note"
          }
        },
        "summary": "Resolve honest activation requirements for a country/number-type/profile-type (override > live did_groups flag > dataset prefix flag; requirement text only documents fields)"
      }
    },
    "/v1/numbers/{number_id}/activation": {
      "get": {
        "responses": {
          "200": {
            "description": "Activation state"
          }
        },
        "summary": "Customer-facing number activation state: instant | pending_verification | approved | needs_info | rejected with blocking items"
      }
    },
    "/v1/numbers/{number_id}/number-rules": {
      "get": {
        "responses": {
          "200": {
            "description": "Number rules"
          }
        },
        "summary": "Compatibility alias for phone-number Number rules"
      },
      "patch": {
        "responses": {
          "200": {
            "description": "Number rules"
          }
        },
        "summary": "Compatibility alias for updating phone-number Number rules"
      }
    },
    "/v1/operator/control-room": {
      "get": {
        "responses": {
          "200": {
            "description": "Control-room bundle"
          }
        },
        "summary": "Read full operator control-room bundle"
      }
    },
    "/v1/operator/didww/identities/{end_user_profile_id}/sync": {
      "post": {
        "responses": {
          "200": {
            "description": "Sync result"
          }
        },
        "summary": "Operator safe-read sync of DIDWW identity.verified and address_verification status back onto the profile/numbers"
      }
    },
    "/v1/operator/launch-readiness": {
      "get": {
        "responses": {
          "200": {
            "description": "Launch readiness"
          }
        },
        "summary": "Read compact redacted launch-goal readiness and action packets"
      }
    },
    "/v1/operator/launch-readiness/refresh": {
      "post": {
        "responses": {
          "200": {
            "description": "Launch readiness"
          }
        },
        "summary": "Regenerate launch-goal readiness from local evidence without live provider actions"
      }
    },
    "/v1/operator/launch-readiness/runbook": {
      "get": {
        "responses": {
          "200": {
            "description": "Launch readiness runbook"
          }
        },
        "summary": "Read Markdown operator runbook generated from the launch-goal readiness report"
      }
    },
    "/v1/operator/provider-health": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider health"
          }
        },
        "summary": "Read redacted provider, DIDWW credential/gate state, launch readiness, media gate, gateway, and suspension health without DIDWW network reads by default"
      }
    },
    "/v1/operator/queues": {
      "get": {
        "responses": {
          "200": {
            "description": "Operator queues"
          }
        },
        "summary": "List filterable operator review queues and next actions"
      }
    },
    "/v1/operator/registration-overrides": {
      "put": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "country": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  },
                  "number_type": {
                    "type": "string"
                  },
                  "provider": {
                    "type": "string"
                  },
                  "registration_required_override": {
                    "enum": [
                      "yes",
                      "no",
                      "clear"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "country",
                  "number_type"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Override state"
          }
        },
        "summary": "Upsert (or clear) an operator registration-requirement override for a provider/country/number-type"
      }
    },
    "/v1/operator/risk-controls": {
      "get": {
        "responses": {
          "200": {
            "description": "Risk controls"
          }
        },
        "summary": "List organization risk controls"
      }
    },
    "/v1/operator/risk-controls/suppressions/{suppression_id}/lift": {
      "post": {
        "responses": {
          "200": {
            "description": "Suppression"
          }
        },
        "summary": "Lift a suppression"
      }
    },
    "/v1/operator/risk-controls/{organization_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Effective risk policy"
          }
        },
        "summary": "Read effective policy for one organization"
      },
      "patch": {
        "responses": {
          "200": {
            "description": "Risk controls"
          }
        },
        "summary": "Update rate limits, spend caps, velocity caps, kill switches, and customer-visible status"
      },
      "post": {
        "responses": {
          "200": {
            "description": "Risk controls"
          }
        },
        "summary": "Update risk controls"
      }
    },
    "/v1/operator/risk-controls/{organization_id}/overrides": {
      "get": {
        "responses": {
          "200": {
            "description": "Overrides"
          }
        },
        "summary": "List temporary risk-control overrides"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Override"
          }
        },
        "summary": "Create temporary override with expiry"
      }
    },
    "/v1/operator/risk-controls/{organization_id}/suppressions": {
      "get": {
        "responses": {
          "200": {
            "description": "Suppressions"
          }
        },
        "summary": "List DNC/STOP suppressions"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Suppression"
          }
        },
        "summary": "Add DNC/STOP suppression"
      }
    },
    "/v1/operator/sch191/cutover-readiness/validate": {
      "post": {
        "responses": {
          "200": {
            "description": "Cutover readiness validation"
          }
        },
        "summary": "Run the offline SCH-191 cutover-readiness wrapper without placing calls or mutating providers"
      }
    },
    "/v1/operator/sch191/live-startup-preflight/validate": {
      "post": {
        "responses": {
          "200": {
            "description": "Live startup preflight validation"
          }
        },
        "summary": "Run the no-call SCH-191 realtime worker startup preflight without ARI connections, calls, SMS, or provider mutations"
      }
    },
    "/v1/operator/sch191/manual-live-artifacts/validate": {
      "post": {
        "responses": {
          "200": {
            "description": "Manual live artifact validation"
          }
        },
        "summary": "Validate approved inbound/outbound SCH-191 live artifact folders without placing calls or mutating providers"
      }
    },
    "/v1/operator/sch191/operator-approval/finalize": {
      "post": {
        "responses": {
          "200": {
            "description": "Operator approval record finalization"
          }
        },
        "summary": "Finalize a fingerprint-bound SCH-191 operator approval record without placing calls or mutating providers"
      }
    },
    "/v1/operator/sch191/provider-network-approval/record": {
      "post": {
        "responses": {
          "200": {
            "description": "Provider-network approval record"
          }
        },
        "summary": "Record explicit SCH-191 provider-network validation approval without contacting STT/LLM/TTS providers"
      }
    },
    "/v1/operator/sch191/provider-stack/validate": {
      "post": {
        "responses": {
          "200": {
            "description": "Provider-stack validation"
          }
        },
        "summary": "Run the no-network SCH-191 realtime provider-stack config check without placing calls or mutating providers"
      }
    },
    "/v1/operator/status-messages": {
      "post": {
        "responses": {
          "200": {
            "description": "Updated customer-visible status"
          }
        },
        "summary": "Edit a customer-visible operator status message"
      }
    },
    "/v1/operator/suspensions": {
      "get": {
        "responses": {
          "200": {
            "description": "Suspensions"
          }
        },
        "summary": "List active or lifted suspensions"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Suspension"
          }
        },
        "summary": "Suspend an organization, traffic mode, provider mutation, recording, gateway, number, or agent resource"
      }
    },
    "/v1/operator/suspensions/{suspension_id}/lift": {
      "post": {
        "responses": {
          "200": {
            "description": "Lifted suspension"
          }
        },
        "summary": "Lift an active suspension"
      }
    },
    "/v1/ops/summary": {
      "get": {
        "responses": {
          "200": {
            "description": "Ops summary"
          }
        },
        "summary": "Operator summary for trials, onboarding, numbers, and calls"
      }
    },
    "/v1/organizations": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrganization"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Workspace created"
          }
        },
        "summary": "Create a sandbox customer workspace when signup mode allows it"
      }
    },
    "/v1/phone-numbers/{number_id}/number-rules": {
      "get": {
        "responses": {
          "200": {
            "description": "Number rules"
          }
        },
        "summary": "Get customer-facing Number rules for a phone number"
      },
      "patch": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NumberRules"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Number rules"
          }
        },
        "summary": "Update customer-facing Number rules for a phone number"
      }
    },
    "/v1/phone-servers": {
      "get": {
        "responses": {
          "200": {
            "description": "Phone servers"
          }
        },
        "summary": "List customer phone servers"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneServer"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Phone server"
          }
        },
        "summary": "Create a customer phone server for self-hosted call media"
      }
    },
    "/v1/phone-servers/{phone_server_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Phone server"
          }
        },
        "summary": "Get one customer phone server"
      },
      "patch": {
        "responses": {
          "200": {
            "description": "Phone server"
          }
        },
        "summary": "Update one customer phone server"
      }
    },
    "/v1/phone-servers/{phone_server_id}/test": {
      "post": {
        "responses": {
          "200": {
            "description": "Verified phone server"
          }
        },
        "summary": "Dry-run verify a customer phone server before assigning Number rules"
      }
    },
    "/v1/policies/evaluate": {
      "post": {
        "responses": {
          "200": {
            "description": "Decision"
          }
        },
        "summary": "Evaluate outbound policy"
      }
    },
    "/v1/pricing/catalog": {
      "get": {
        "responses": {
          "200": {
            "description": "Catalog"
          }
        },
        "summary": "List pricing plans"
      }
    },
    "/v1/pricing/estimate": {
      "post": {
        "responses": {
          "200": {
            "description": "Estimate"
          }
        },
        "summary": "Estimate monthly platform cost"
      }
    },
    "/v1/provider-accounts": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider accounts"
          }
        },
        "summary": "List provider accounts visible to an organization"
      }
    },
    "/v1/provider-accounts/{provider_account_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider account"
          }
        },
        "summary": "Get one provider account"
      }
    },
    "/v1/provider-mutations": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider mutations"
          }
        },
        "summary": "List provider mutation requests"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Provider mutation"
          }
        },
        "summary": "Create a provider mutation dry-run preview"
      }
    },
    "/v1/provider-mutations/{request_id}": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider mutation"
          }
        },
        "summary": "Inspect one provider mutation request"
      }
    },
    "/v1/provider-mutations/{request_id}/approve": {
      "post": {
        "responses": {
          "200": {
            "description": "Approved provider mutation"
          }
        },
        "summary": "Approve a provider mutation request"
      }
    },
    "/v1/provider-mutations/{request_id}/execute": {
      "post": {
        "responses": {
          "200": {
            "description": "Executed or blocked provider mutation"
          }
        },
        "summary": "Execute an approved provider mutation when live gates are enabled"
      }
    },
    "/v1/provider/didww/available-dids-evidence-report": {
      "get": {
        "responses": {
          "200": {
            "description": "Redacted available_dids evidence report"
          }
        },
        "summary": "Export redacted cached DIDWW available_dids evidence for SCH-181 readiness"
      }
    },
    "/v1/provider/didww/available-number-cache": {
      "get": {
        "responses": {
          "200": {
            "description": "Cached DIDWW available numbers"
          }
        },
        "summary": "Read cached exact DIDWW available_dids.id numbers for operator selection"
      }
    },
    "/v1/provider/didww/available-numbers": {
      "get": {
        "responses": {
          "200": {
            "description": "Available numbers"
          }
        },
        "summary": "Search DIDWW available numbers safely"
      }
    },
    "/v1/provider/didww/balance": {
      "get": {
        "responses": {
          "200": {
            "description": "Balance"
          }
        },
        "summary": "Read DIDWW balance safely"
      }
    },
    "/v1/provider/didww/catalog": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW catalog"
          }
        },
        "summary": "Read the stored DIDWW catalog for operator pricing and requirements review"
      }
    },
    "/v1/provider/didww/dids": {
      "get": {
        "responses": {
          "200": {
            "description": "Owned DIDs"
          }
        },
        "summary": "Read DIDWW owned DIDs safely"
      }
    },
    "/v1/provider/didww/inventory": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW safe-read inventory"
          }
        },
        "summary": "Consolidated DIDWW safe-read inventory bundle"
      }
    },
    "/v1/provider/didww/logs": {
      "get": {
        "responses": {
          "200": {
            "description": "Logs"
          }
        },
        "summary": "Read DIDWW CDR export listings safely"
      }
    },
    "/v1/provider/didww/number-price-lists/import": {
      "post": {
        "responses": {
          "201": {
            "description": "Imported number price list"
          }
        },
        "summary": "Import a DIDWW DID/Toll-Free setup/monthly price-list artifact without provider mutation"
      }
    },
    "/v1/provider/didww/number-quote": {
      "get": {
        "responses": {
          "200": {
            "description": "Available number quote"
          }
        },
        "summary": "Quote one DIDWW available_dids.id before order"
      }
    },
    "/v1/provider/didww/pricing-artifact-inbox": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW pricing artifact inbox"
          }
        },
        "summary": "Scan local DIDWW pricing downloads and return a found/missing artifact checklist without provider network calls"
      }
    },
    "/v1/provider/didww/pricing-artifacts/import-found": {
      "post": {
        "responses": {
          "201": {
            "description": "Imported found pricing artifacts"
          }
        },
        "summary": "Import all local DIDWW pricing artifacts classified as found by the pricing inbox without provider mutation"
      }
    },
    "/v1/provider/didww/pricing-sources": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW pricing-source readiness"
          }
        },
        "summary": "Read DIDWW pricing-source readiness before quoting or ordering"
      }
    },
    "/v1/provider/didww/rate-cards": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW rate cards"
          }
        },
        "summary": "Read imported DIDWW traffic rate cards"
      }
    },
    "/v1/provider/didww/rate-cards/import": {
      "post": {
        "responses": {
          "201": {
            "description": "Imported rate card"
          }
        },
        "summary": "Import a DIDWW CSV/XLS/XLSX traffic rate card without provider mutation"
      }
    },
    "/v1/provider/didww/requirements": {
      "get": {
        "responses": {
          "200": {
            "description": "Requirements"
          }
        },
        "summary": "Read DIDWW requirements and customer terms safely"
      }
    },
    "/v1/provider/didww/sync-runs": {
      "get": {
        "responses": {
          "200": {
            "description": "DIDWW sync runs"
          }
        },
        "summary": "List DIDWW sync/import/safe-read evidence"
      },
      "post": {
        "responses": {
          "201": {
            "description": "DIDWW sync run"
          }
        },
        "summary": "Run and record a safe DIDWW sync/read such as DID Groups catalog sync, without provider mutation"
      }
    },
    "/v1/provider/didww/traffic-rate-evidence": {
      "post": {
        "responses": {
          "201": {
            "description": "Recorded traffic-rate evidence"
          }
        },
        "summary": "Record reviewed DIDWW traffic-rate evidence without provider mutation"
      }
    },
    "/v1/provider/didww/traffic-rate-evidence/bulk": {
      "post": {
        "responses": {
          "201": {
            "description": "Recorded bulk traffic-rate evidence"
          }
        },
        "summary": "Record multiple reviewed DIDWW traffic-rate evidence rows without provider mutation"
      }
    },
    "/v1/provider/didww/usage-records/import": {
      "post": {
        "responses": {
          "200": {
            "description": "Usage import result"
          }
        },
        "summary": "Import a DIDWW CDR, invoice, SMS, or usage CSV into usage records"
      }
    },
    "/v1/recording-retention/candidates": {
      "get": {
        "responses": {
          "200": {
            "description": "Retention candidates"
          }
        },
        "summary": "List recordings eligible for retention cleanup"
      }
    },
    "/v1/recording-retention/run": {
      "post": {
        "responses": {
          "200": {
            "description": "Retention run"
          }
        },
        "summary": "Dry-run or execute recording/artifact retention cleanup"
      }
    },
    "/v1/regulatory-requirements": {
      "get": {
        "responses": {
          "200": {
            "description": "Requirements"
          }
        },
        "summary": "List DIDWW country and number-type requirements with simple onboarding terms and cache metadata"
      }
    },
    "/v1/self-hosted/install-plan": {
      "get": {
        "responses": {
          "200": {
            "description": "Self-hosted install plan"
          }
        },
        "summary": "Fetch a mode-specific self-hosted or customer-hosted gateway install plan"
      }
    },
    "/v1/trial-calls": {
      "get": {
        "responses": {
          "200": {
            "description": "Trial calls"
          }
        },
        "summary": "List free trial calls"
      },
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrialCall"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Trial call"
          }
        },
        "summary": "Create a shared demo-number trial PIN"
      }
    },
    "/v1/trial-calls/route": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RouteTrialCall"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Routed trial call"
          }
        },
        "summary": "Route an inbound shared-number call by PIN"
      }
    },
    "/v1/usage": {
      "get": {
        "responses": {
          "200": {
            "description": "Usage"
          }
        },
        "summary": "Get usage summary"
      }
    },
    "/v1/usage/daily": {
      "get": {
        "responses": {
          "200": {
            "description": "Daily usage"
          }
        },
        "summary": "Get daily usage summary"
      }
    },
    "/v1/usage/monthly": {
      "get": {
        "responses": {
          "200": {
            "description": "Monthly usage"
          }
        },
        "summary": "Get monthly usage summary"
      }
    },
    "/v1/wallet": {
      "get": {
        "responses": {
          "200": {
            "description": "Wallet summary"
          }
        },
        "summary": "Read wallet balance and low-balance readiness against recurring and reserved costs"
      }
    },
    "/v1/wallet/ledger": {
      "get": {
        "responses": {
          "200": {
            "description": "Wallet ledger"
          }
        },
        "summary": "List org-level wallet ledger entries and linked usage/call refs"
      }
    },
    "/v1/wallet/topups": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Topup"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Wallet balance"
          }
        },
        "summary": "Load calling credits"
      }
    },
    "/v1/web-calls": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebCall"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Web test call"
          }
        },
        "summary": "Create a non-PSTN browser web-call test session"
      }
    },
    "/v1/webhooks/didit": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Webhook processing result"
          }
        },
        "summary": "didit.me status webhook (HMAC-signed, idempotent on event_id); Approved fetches the decision once"
      }
    },
    "/v1/worker-heartbeats": {
      "get": {
        "responses": {
          "200": {
            "description": "Worker heartbeats"
          }
        },
        "summary": "List worker heartbeats"
      },
      "post": {
        "responses": {
          "200": {
            "description": "Worker heartbeat"
          }
        },
        "summary": "Record a worker heartbeat"
      }
    },
    "/v1/worker-jobs": {
      "get": {
        "responses": {
          "200": {
            "description": "Worker jobs"
          }
        },
        "summary": "List background jobs"
      },
      "post": {
        "responses": {
          "201": {
            "description": "Worker job"
          }
        },
        "summary": "Queue a background job"
      }
    },
    "/v1/worker-jobs/claim": {
      "post": {
        "responses": {
          "200": {
            "description": "Claimed job"
          }
        },
        "summary": "Claim the next ready background job"
      }
    },
    "/v1/worker-jobs/{job_id}/call-artifact-import-preview": {
      "get": {
        "responses": {
          "200": {
            "description": "Call artifact import preview"
          }
        },
        "summary": "Preview a call artifact import worker job without importing files"
      }
    },
    "/v1/worker-jobs/{job_id}/call-artifact-import/execute": {
      "post": {
        "responses": {
          "200": {
            "description": "Call artifact import execution"
          }
        },
        "summary": "Execute a claimed call artifact import worker job"
      }
    },
    "/v1/worker-jobs/{job_id}/complete": {
      "post": {
        "responses": {
          "200": {
            "description": "Worker job"
          }
        },
        "summary": "Mark a job succeeded"
      }
    },
    "/v1/worker-jobs/{job_id}/fail": {
      "post": {
        "responses": {
          "200": {
            "description": "Worker job"
          }
        },
        "summary": "Mark a job failed or schedule retry"
      }
    },
    "/v1/worker-jobs/{job_id}/inbound-route-preview": {
      "get": {
        "responses": {
          "200": {
            "description": "Inbound route worker preview"
          }
        },
        "summary": "Preview an inbound live-media route worker handoff without bridging a call"
      }
    },
    "/v1/worker-jobs/{job_id}/inbound-route/execute": {
      "post": {
        "responses": {
          "200": {
            "description": "Inbound route worker execution"
          }
        },
        "summary": "Dry-run or complete a claimed inbound route worker job with a media handler"
      }
    },
    "/v1/worker-jobs/{job_id}/provider-sync-preview": {
      "get": {
        "responses": {
          "200": {
            "description": "Provider sync preview"
          }
        },
        "summary": "Preview a DIDWW provider-sync worker job without running the provider read"
      }
    },
    "/v1/worker-jobs/{job_id}/provider-sync/execute": {
      "post": {
        "responses": {
          "200": {
            "description": "Provider sync execution"
          }
        },
        "summary": "Execute a claimed DIDWW provider-sync worker job"
      }
    },
    "/v1/worker-jobs/{job_id}/retry": {
      "post": {
        "responses": {
          "200": {
            "description": "Worker job"
          }
        },
        "summary": "Retry a failed job"
      }
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:18765"
    }
  ]
}