{
    "openapi": "3.1.0",
    "info": {
        "title": "ISPbills Public API",
        "version": "2.0.0",
        "description": "REST API v2 for customers, billing, packages, network inventory, monitoring, SMS, VPN and webhook registrations. Obtain owner-provisioned client credentials, then exchange them for an opaque Bearer token. This is not a general OAuth authorization-code service. The shared API throttle is 60 requests per minute per authenticated user or IP; protected v2 requests also have a configurable per-client minute limit. No general Idempotency-Key or dry-run support is implemented. Do not blindly retry writes. Request schemas come from route validation; most success-response resource fields are intentionally not yet fully modeled. See the integration guide for scope enforcement, token-cache delay, pagination, errors, retry safety and webhook limitations.",
        "contact": {
            "name": "ISPbills Support",
            "url": "https://ispbills.com/support/",
            "email": "support@ispbills.com"
        },
        "termsOfService": "https://ispbills.com/terms/"
    },
    "servers": [
        {
            "url": "https://app.ispbills.com/api/v2"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/auth/token": {
            "post": {
                "operationId": "v2.auth.token",
                "description": "Exchange an active API client ID and secret for a newly generated Bearer token and granted scopes.\n\nAccess: Public credentials.\n\nThe client secret is shown only when the API client is created or regenerated. Store it securely.",
                "summary": "Create an access token",
                "tags": [
                    "Authentication"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "client_id": {
                                        "type": "string"
                                    },
                                    "client_secret": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "client_id",
                                    "client_secret"
                                ]
                            },
                            "example": {
                                "client_id": "your-client-id",
                                "client_secret": "your-client-secret"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "access_token",
                                        "token_type",
                                        "scopes"
                                    ],
                                    "properties": {
                                        "access_token": {
                                            "type": "string",
                                            "minLength": 64,
                                            "maxLength": 64
                                        },
                                        "token_type": {
                                            "type": "string",
                                            "enum": [
                                                "Bearer"
                                            ]
                                        },
                                        "scopes": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "security": [
                    {}
                ]
            }
        },
        "/auth/revoke": {
            "post": {
                "operationId": "v2.auth.revoke",
                "description": "Clear the stored Bearer token used for this request. A cached token can remain accepted for up to five minutes.\n\nAccess: Bearer token.\n\nObtain a new token with the client ID and secret when access is needed again.",
                "summary": "Revoke the current token",
                "tags": [
                    "Authentication"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/billing/bills": {
            "get": {
                "operationId": "bills.index",
                "description": "Return tenant bills in newest-first order.\n\nAccess: Bearer token.",
                "summary": "List bills",
                "tags": [
                    "Billing"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ]
            },
            "post": {
                "operationId": "bills.store",
                "description": "Create a customer bill and apply the tenant’s configured inclusive VAT breakdown.\n\nAccess: Bearer token.",
                "summary": "Create a bill",
                "tags": [
                    "Billing"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "customer_id": {
                                        "type": "integer"
                                    },
                                    "amount": {
                                        "type": "number"
                                    },
                                    "currency": {
                                        "type": "string"
                                    },
                                    "due_date": {
                                        "type": "string"
                                    },
                                    "package_name": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "customer_id",
                                    "amount",
                                    "due_date"
                                ]
                            },
                            "example": {
                                "customer_id": 123,
                                "amount": 1200,
                                "currency": "BDT",
                                "due_date": "2026-10-15",
                                "package_name": "20 Mbps"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "Resource created successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/billing/bills/{id}": {
            "get": {
                "operationId": "bills.show",
                "description": "Return one bill when it belongs to the API client tenant.\n\nAccess: Bearer token.",
                "summary": "Get a bill",
                "tags": [
                    "Billing"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "put": {
                "operationId": "bills.update",
                "description": "Update supplied bill fields and recalculate VAT when the amount changes.\n\nAccess: Bearer token.",
                "summary": "Update a bill",
                "tags": [
                    "Billing"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "amount": {
                                        "type": "number"
                                    },
                                    "currency": {
                                        "type": "string"
                                    },
                                    "due_date": {
                                        "type": "string"
                                    },
                                    "is_paid": {
                                        "type": "boolean"
                                    }
                                }
                            },
                            "example": {
                                "amount": 1300,
                                "currency": "BDT",
                                "due_date": "2026-10-20",
                                "is_paid": false
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "delete": {
                "operationId": "bills.destroy",
                "description": "Delete one tenant-owned customer bill.\n\nAccess: Bearer token.\n\nThis is destructive. Read the bill first and avoid retrying an ambiguous delete.",
                "summary": "Delete a bill",
                "tags": [
                    "Billing"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/billing/payments": {
            "get": {
                "operationId": "v2.billing.payments",
                "description": "Return payment records owned by the API client operator.\n\nAccess: Bearer token.",
                "summary": "List payments",
                "tags": [
                    "Billing"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ]
            }
        },
        "/customers": {
            "get": {
                "operationId": "v2.customers.index",
                "description": "Return customers owned by the API client operator in newest-first order.\n\nAccess: customers:read.",
                "summary": "List customers",
                "tags": [
                    "Customers"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ]
            },
            "post": {
                "operationId": "v2.customers.store",
                "description": "Create an active customer in the operator’s RADIUS customer store.\n\nAccess: customers:write.\n\nUse a unique username and a mobile number valid for the operator’s configured country.",
                "summary": "Create a customer",
                "tags": [
                    "Customers"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "username": {
                                        "type": "string"
                                    },
                                    "name": {
                                        "type": "string"
                                    },
                                    "mobile": {
                                        "type": "string"
                                    },
                                    "password": {
                                        "type": "string"
                                    },
                                    "connection_type": {
                                        "type": "string"
                                    },
                                    "billing_type": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "username",
                                    "name",
                                    "mobile",
                                    "password",
                                    "connection_type",
                                    "billing_type"
                                ]
                            },
                            "example": {
                                "username": "01700000000",
                                "name": "Example Subscriber",
                                "mobile": "01700000000",
                                "password": "change-me-123",
                                "connection_type": "PPPoE",
                                "billing_type": "Monthly"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "Resource created successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/customers/{id}": {
            "get": {
                "operationId": "v2.customers.show",
                "description": "Return one tenant-owned customer together with up to ten recent bills.\n\nAccess: customers:read.",
                "summary": "Get a customer",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "put": {
                "operationId": "v2.customers.update",
                "description": "Update the supplied name, mobile number, or status fields for a tenant-owned customer.\n\nAccess: customers:write.",
                "summary": "Update a customer",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "mobile": {
                                        "type": "string"
                                    },
                                    "status": {
                                        "type": "string"
                                    }
                                }
                            },
                            "example": {
                                "name": "Updated Subscriber",
                                "mobile": "01700000001",
                                "status": "active"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "delete": {
                "operationId": "v2.customers.destroy",
                "description": "Delete a customer belonging to the API client operator.\n\nAccess: customers:write.\n\nThis is destructive. Confirm the customer ID in a GET request first.",
                "summary": "Delete a customer",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/customers/{id}/bills": {
            "get": {
                "operationId": "v2.customers.bills",
                "description": "Return the selected customer’s tenant-scoped billing records.\n\nAccess: customers:read.",
                "summary": "List customer bills",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/customers/{id}/payments": {
            "get": {
                "operationId": "v2.customers.payments",
                "description": "Return the selected customer’s operator-scoped payment records.\n\nAccess: customers:read.",
                "summary": "List customer payments",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/customers/{id}/subscriptions": {
            "get": {
                "operationId": "v2.customers.subscriptions",
                "description": "Return subscription-style bill records for the selected customer.\n\nAccess: customers:read.",
                "summary": "List customer subscriptions",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 20, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/customers/{id}/usage": {
            "get": {
                "operationId": "v2.customers.usage",
                "description": "Return up to twenty recent RADIUS sessions, including timestamps, octets and calling station.\n\nAccess: customers:read.",
                "summary": "Get customer usage",
                "tags": [
                    "Customers"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/monitoring/zabbix/hosts": {
            "get": {
                "operationId": "v2.monitoring.zabbix.hosts",
                "description": "Return hosts from the tenant’s configured Zabbix servers.\n\nAccess: Bearer token.",
                "summary": "List Zabbix hosts",
                "tags": [
                    "Monitoring"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/monitoring/zabbix/problems": {
            "get": {
                "operationId": "v2.monitoring.zabbix.problems",
                "description": "Return up to one hundred recent problems for tenant-owned Zabbix hosts.\n\nAccess: Bearer token.",
                "summary": "List Zabbix problems",
                "tags": [
                    "Monitoring"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/monitoring/devices": {
            "get": {
                "operationId": "v2.monitoring.devices",
                "description": "Return combined Ubiquiti and Cambium device status records.\n\nAccess: Bearer token.",
                "summary": "List monitored devices",
                "tags": [
                    "Monitoring"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/monitoring/status-checks": {
            "get": {
                "operationId": "v2.monitoring.status-checks",
                "description": "Return configured service checks and each check’s latest result.\n\nAccess: Bearer token.",
                "summary": "List status checks",
                "tags": [
                    "Monitoring"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/network/routers": {
            "get": {
                "operationId": "v2.network.routers",
                "description": "Return tenant RADIUS NAS/router records with name, address and model.\n\nAccess: Bearer token.",
                "summary": "List routers",
                "tags": [
                    "Network"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/network/olts": {
            "get": {
                "operationId": "v2.network.olts",
                "description": "Return OLT inventory assigned to the API client operator.\n\nAccess: Bearer token.",
                "summary": "List OLTs",
                "tags": [
                    "Network"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/network/onus": {
            "get": {
                "operationId": "v2.network.onus",
                "description": "Return paginated ONU inventory with serial, status and OLT association.\n\nAccess: Bearer token.",
                "summary": "List ONUs",
                "tags": [
                    "Network"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 50, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ]
            }
        },
        "/network/pools": {
            "get": {
                "operationId": "v2.network.pools",
                "description": "Return address pools owned by the API client operator.\n\nAccess: Bearer token.",
                "summary": "List IPv4 pools",
                "tags": [
                    "Network"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/packages": {
            "get": {
                "operationId": "v2.packages.index",
                "description": "Return packages with speed, price, currency and validity information.\n\nAccess: Bearer token.",
                "summary": "List packages",
                "tags": [
                    "Packages"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                },
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "Page number; default 1.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "example": 1
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Rows per page; default 50, maximum 100.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        },
                        "example": 20
                    }
                ]
            }
        },
        "/sms/balance": {
            "get": {
                "operationId": "v2.sms.balance",
                "description": "Return the effective gateway and balance of the account responsible for this operator’s SMS cost.\n\nAccess: Bearer token.",
                "summary": "Get SMS balance",
                "tags": [
                    "SMS"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/sms/send": {
            "post": {
                "operationId": "v2.sms.send",
                "description": "Send one message through the operator’s effective gateway and record it in SMS history.\n\nAccess: sms:send.",
                "summary": "Send one SMS",
                "tags": [
                    "SMS"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "phone": {
                                        "type": "string"
                                    },
                                    "message": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "phone",
                                    "message"
                                ]
                            },
                            "example": {
                                "phone": "01700000000",
                                "message": "Your invoice has been generated."
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "500": {
                        "description": "An unexpected server error occurred.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Failed to send SMS."
                                        }
                                    },
                                    "required": [
                                        "success",
                                        "message"
                                    ]
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/sms/broadcast": {
            "post": {
                "operationId": "v2.sms.broadcast",
                "description": "Send the same message to between one and five hundred phone numbers.\n\nAccess: sms:send.\n\nThe response reports accepted and failed counts. A successful request can still contain individual failed deliveries.",
                "summary": "Send an SMS broadcast",
                "tags": [
                    "SMS"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "message": {
                                        "type": "string"
                                    },
                                    "phones": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "minItems": 1,
                                        "maxItems": 500
                                    }
                                },
                                "required": [
                                    "message",
                                    "phones"
                                ]
                            },
                            "example": {
                                "phones": [
                                    "01700000000",
                                    "01800000000"
                                ],
                                "message": "Scheduled maintenance begins at 01:00."
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "403": {
                        "description": "The token does not have permission for this operation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Insufficient scope"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/vpn/accounts": {
            "get": {
                "operationId": "v2.vpn.accounts",
                "description": "Return tenant VPN accounts and their provisioning/revocation state.\n\nAccess: Bearer token.",
                "summary": "List VPN accounts",
                "tags": [
                    "VPN"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/vpn/accounts/{id}/config": {
            "get": {
                "operationId": "v2.vpn.config",
                "description": "Generate the client configuration for a tenant-owned VPN account.\n\nAccess: Bearer token.\n\nThe response contains sensitive configuration. Do not log or cache it.",
                "summary": "Get VPN client configuration",
                "tags": [
                    "VPN"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "anyOf": [
                                        {
                                            "type": "object",
                                            "properties": {
                                                "error": {
                                                    "type": "string",
                                                    "example": "No VPN server linked to this account."
                                                }
                                            },
                                            "required": [
                                                "error"
                                            ]
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "error": {
                                                    "type": "string",
                                                    "example": "Not found"
                                                }
                                            },
                                            "required": [
                                                "error"
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/webhooks": {
            "get": {
                "operationId": "v2.webhooks.index",
                "description": "Return the API client tenant’s webhook registrations without their secrets.\n\nAccess: Bearer token.",
                "summary": "List webhook endpoints",
                "tags": [
                    "Webhooks"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "post": {
                "operationId": "v2.webhooks.store",
                "description": "Register a webhook receiver and return its generated signing secret. Use HTTPS for the receiver.\n\nAccess: Bearer token.\n\nSave the returned secret securely. Registration does not guarantee event production; automatic business-event dispatch is not currently wired.",
                "summary": "Create a webhook endpoint",
                "tags": [
                    "Webhooks"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string"
                                    },
                                    "events_json": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "minItems": 1
                                    },
                                    "is_active": {
                                        "type": "boolean"
                                    }
                                },
                                "required": [
                                    "url",
                                    "events_json"
                                ]
                            },
                            "example": {
                                "url": "https://example.com/webhooks/ispbills",
                                "events_json": [
                                    "payment.received",
                                    "customer.updated"
                                ],
                                "is_active": true
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "201": {
                        "description": "Resource created successfully.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        },
        "/webhooks/{id}": {
            "put": {
                "operationId": "v2.webhooks.update",
                "description": "Change the URL, subscribed events, or active state of a tenant-owned webhook.\n\nAccess: Bearer token.",
                "summary": "Update a webhook endpoint",
                "tags": [
                    "Webhooks"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "url": {
                                        "type": "string"
                                    },
                                    "events_json": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "minItems": 1
                                    },
                                    "is_active": {
                                        "type": "boolean"
                                    }
                                }
                            },
                            "example": {
                                "events_json": [
                                    "payment.received"
                                ],
                                "is_active": true
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/ApiValidationError"
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            },
            "delete": {
                "operationId": "v2.webhooks.destroy",
                "description": "Remove a tenant-owned webhook registration.\n\nAccess: Bearer token.\n\nThis stops all future deliveries to the endpoint.",
                "summary": "Delete a webhook endpoint",
                "tags": [
                    "Webhooks"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful response.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "description": "JSON response; resource fields are not yet fully modeled.",
                                    "additionalProperties": true
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The requested tenant-owned resource was not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "example": "Not found"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/ApiUnauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/ApiRateLimit"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "description": "Token returned by POST /auth/token.",
                "scheme": "bearer",
                "bearerFormat": "API token"
            }
        },
        "responses": {
            "ValidationException": {
                "description": "Validation error",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "description": "Errors overview."
                                },
                                "errors": {
                                    "type": "object",
                                    "description": "A detailed description of each field that failed validation.",
                                    "additionalProperties": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            },
                            "required": [
                                "message",
                                "errors"
                            ]
                        }
                    }
                }
            },
            "ApiUnauthorized": {
                "description": "Missing or invalid Bearer token, or invalid client credentials during token exchange.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "required": [
                                "error"
                            ],
                            "properties": {
                                "error": {
                                    "type": "string"
                                }
                            }
                        },
                        "example": {
                            "error": "Unauthorized"
                        }
                    }
                }
            },
            "ApiRateLimit": {
                "description": "Shared API or per-client limit exceeded. The client limiter returns retry_after seconds in JSON; the shared throttle uses Retry-After.",
                "headers": {
                    "Retry-After": {
                        "description": "Seconds to wait, when returned by the shared throttle. Not set by the per-client limiter.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "error": {
                                    "type": "string"
                                },
                                "message": {
                                    "type": "string"
                                },
                                "retry_after": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 60
                                }
                            }
                        },
                        "examples": {
                            "clientLimit": {
                                "value": {
                                    "error": "Too Many Requests",
                                    "retry_after": 42
                                }
                            },
                            "sharedLimit": {
                                "value": {
                                    "message": "Too Many Attempts."
                                }
                            }
                        }
                    }
                }
            },
            "ApiValidationError": {
                "description": "Invalid input. Field validation returns message/errors; controller checks can return error or success/message instead.",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "anyOf": [
                                {
                                    "required": [
                                        "error"
                                    ]
                                },
                                {
                                    "required": [
                                        "message"
                                    ]
                                }
                            ],
                            "properties": {
                                "error": {
                                    "type": "string"
                                },
                                "message": {
                                    "type": "string"
                                },
                                "success": {
                                    "type": "boolean"
                                },
                                "errors": {
                                    "type": "object",
                                    "additionalProperties": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        },
                        "examples": {
                            "validation": {
                                "value": {
                                    "message": "The client id field is required.",
                                    "errors": {
                                        "client_id": [
                                            "The client id field is required."
                                        ]
                                    }
                                }
                            },
                            "controller": {
                                "value": {
                                    "error": "Invalid mobile number"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "externalDocs": {
        "description": "Authentication, rate limits, errors, retries and webhook delivery",
        "url": "https://ispbills.com/api-guide.md"
    },
    "tags": [
        {
            "name": "Authentication",
            "description": "Create and revoke API access tokens."
        },
        {
            "name": "Customers",
            "description": "Manage subscribers and inspect their billing and usage."
        },
        {
            "name": "Billing",
            "description": "Create and manage customer bills and payment records."
        },
        {
            "name": "Packages",
            "description": "Read the packages available to the API client owner."
        },
        {
            "name": "Network",
            "description": "Read routers, OLTs, ONUs and address pools."
        },
        {
            "name": "Monitoring",
            "description": "Read Zabbix, device and service-check health data."
        },
        {
            "name": "SMS",
            "description": "Inspect the effective SMS account and send messages."
        },
        {
            "name": "VPN",
            "description": "Read provisioned VPN accounts and their client configuration."
        },
        {
            "name": "Webhooks",
            "description": "Register and manage signed event-delivery endpoints."
        }
    ]
}