{
    "openapi": "3.1.0",
    "info": {
        "title": "Proxonym account API",
        "version": "v1",
        "summary": "Manage a Proxonym proxy account: plans and balances, usage, proxy lists, IP whitelist and sub-users.",
        "description": "Authenticate with an account API key created in the dashboard, sent as `Authorization: Bearer <API_KEY>`. Each key may send 60 requests per minute; every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Errors use one JSON shape: `{\"error\": {\"code\", \"message\"}}`. Human documentation: https://proxonym.com/docs/api",
        "termsOfService": "https://proxonym.com/terms",
        "contact": {
            "name": "Proxonym support",
            "url": "https://proxonym.com/contact"
        }
    },
    "externalDocs": {
        "description": "API reference",
        "url": "https://proxonym.com/docs/api"
    },
    "servers": [
        {
            "url": "https://api.proxonym.com/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Account"
        },
        {
            "name": "Usage"
        },
        {
            "name": "Proxy lists"
        },
        {
            "name": "Whitelist"
        },
        {
            "name": "Sub-users"
        }
    ],
    "paths": {
        "/account": {
            "get": {
                "tags": [
                    "Account"
                ],
                "operationId": "getAccount",
                "summary": "Account, credit, traffic balances and active plans",
                "responses": {
                    "200": {
                        "description": "The account",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Account"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/usage": {
            "get": {
                "tags": [
                    "Usage"
                ],
                "operationId": "getUsage",
                "summary": "Usage of one product over time",
                "parameters": [
                    {
                        "name": "product",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "residential",
                                "unlimited",
                                "mobile",
                                "isp",
                                "datacenter",
                                "dedicated",
                                "serp"
                            ]
                        }
                    },
                    {
                        "name": "granularity",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "day",
                                "hour"
                            ],
                            "default": "day"
                        },
                        "description": "Up to 366 days at day granularity, 31 days at hour granularity."
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "ISO 8601 date or UTC timestamp. Default: 7 days before `to`."
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "ISO 8601 date or UTC timestamp. Default: now."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Usage series",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Usage"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing product",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid product, granularity or range",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/proxies/{product}": {
            "get": {
                "tags": [
                    "Proxy lists"
                ],
                "operationId": "listProxies",
                "summary": "IPs of your active datacenter, ISP or dedicated plans",
                "parameters": [
                    {
                        "name": "product",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "datacenter",
                                "isp",
                                "dedicated"
                            ]
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "txt"
                            ],
                            "default": "json"
                        },
                        "description": "`txt` returns one proxy per line: `ip:port` for datacenter, `ip:port:username:password` otherwise."
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^[a-z]{2}$"
                        },
                        "description": "Lowercase ISO 3166-1 alpha-2 code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The proxy list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ProxyList"
                                }
                            },
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "No active plan for this product (code product_not_active)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No list exists for this product",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid format or country",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/whitelist": {
            "get": {
                "tags": [
                    "Whitelist"
                ],
                "operationId": "listWhitelist",
                "summary": "Whitelisted IPs (datacenter authentication)",
                "responses": {
                    "200": {
                        "description": "Whitelist",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "limit",
                                        "ips"
                                    ],
                                    "properties": {
                                        "limit": {
                                            "type": "integer",
                                            "const": 3
                                        },
                                        "ips": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/WhitelistIp"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            },
            "post": {
                "tags": [
                    "Whitelist"
                ],
                "operationId": "addWhitelistIp",
                "summary": "Whitelist an IP",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ip"
                                ],
                                "properties": {
                                    "ip": {
                                        "type": "string",
                                        "description": "IPv4 or IPv6 address"
                                    },
                                    "label": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Added",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WhitelistIp"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing ip",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Already on the whitelist (code already_exists)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid IP, or all 3 slots in use (code whitelist_full)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/whitelist/{ip}": {
            "delete": {
                "tags": [
                    "Whitelist"
                ],
                "operationId": "removeWhitelistIp",
                "summary": "Remove a whitelisted IP",
                "parameters": [
                    {
                        "name": "ip",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "URL-encoded IPv4 or IPv6 address"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "ip": {
                                            "type": "string"
                                        },
                                        "deleted": {
                                            "type": "boolean",
                                            "const": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Not on the whitelist",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/sub-users": {
            "get": {
                "tags": [
                    "Sub-users"
                ],
                "operationId": "listSubUsers",
                "summary": "Sub-users with their credentials and traffic",
                "responses": {
                    "200": {
                        "description": "Sub-users",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "sub_users"
                                    ],
                                    "properties": {
                                        "sub_users": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/SubUser"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            },
            "post": {
                "tags": [
                    "Sub-users"
                ],
                "operationId": "createSubUser",
                "summary": "Create a sub-user",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "traffic_limit_gb": {
                                        "type": [
                                            "number",
                                            "null"
                                        ],
                                        "description": "null for no limit"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SubUser"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Missing or invalid field",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Name already used (code already_exists)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        },
        "/sub-users/{id}": {
            "patch": {
                "tags": [
                    "Sub-users"
                ],
                "operationId": "updateSubUser",
                "summary": "Rename, limit, disable or reset a sub-user",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubUserId"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "traffic_limit_gb": {
                                        "type": [
                                            "number",
                                            "null"
                                        ]
                                    },
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "disabled"
                                        ]
                                    },
                                    "reset_password": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SubUser"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid field type",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No sub-user with this ID",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Name already used (code already_exists)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            },
            "delete": {
                "tags": [
                    "Sub-users"
                ],
                "operationId": "deleteSubUser",
                "summary": "Delete a sub-user",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SubUserId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Deleted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "id": {
                                            "type": "string"
                                        },
                                        "deleted": {
                                            "type": "boolean",
                                            "const": true
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No sub-user with this ID",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServerError"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Account API key from the dashboard"
            }
        },
        "parameters": {
            "SubUserId": {
                "name": "id",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "string",
                    "pattern": "^su_[a-z0-9]+$"
                }
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "API key missing, malformed or revoked (code invalid_api_key)",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "More than 60 requests in the current minute (code rate_limited)",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Seconds to wait"
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "ServerError": {
                "description": "Unexpected error (code internal_error); retry with exponential backoff",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "examples": [
                                    "invalid_api_key",
                                    "rate_limited",
                                    "not_found",
                                    "validation_failed",
                                    "already_exists",
                                    "product_not_active",
                                    "whitelist_full"
                                ]
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Account": {
                "type": "object",
                "required": [
                    "id",
                    "email",
                    "created_at",
                    "credit_usd",
                    "balances",
                    "plans"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "examples": [
                            "acc_x7k2m9"
                        ]
                    },
                    "email": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "credit_usd": {
                        "type": "number",
                        "description": "Prepaid balance in USD"
                    },
                    "balances": {
                        "type": "object",
                        "properties": {
                            "residential": {
                                "type": "object",
                                "description": "GB packs, shared by residential and mobile traffic",
                                "properties": {
                                    "gb_remaining": {
                                        "type": "number"
                                    },
                                    "expires_at": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "format": "date-time"
                                    },
                                    "packs": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "gb_purchased": {
                                                    "type": "number"
                                                },
                                                "gb_remaining": {
                                                    "type": "number"
                                                },
                                                "purchased_at": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "expires_at": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "format": "date-time"
                                                }
                                            }
                                        }
                                    }
                                }
                            },
                            "datacenter": {
                                "type": "object",
                                "properties": {
                                    "gb_remaining": {
                                        "type": [
                                            "number",
                                            "null"
                                        ],
                                        "description": "null on unlimited bandwidth"
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    }
                                }
                            }
                        }
                    },
                    "plans": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Plan"
                        }
                    }
                }
            },
            "Plan": {
                "type": "object",
                "required": [
                    "id",
                    "product",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "examples": [
                            "pl_8f2k1c"
                        ]
                    },
                    "product": {
                        "type": "string",
                        "enum": [
                            "unlimited",
                            "datacenter",
                            "isp",
                            "dedicated",
                            "serp"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "provisioning"
                        ]
                    },
                    "started_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "expires_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date-time"
                    },
                    "bandwidth_mbps": {
                        "type": "integer",
                        "description": "unlimited"
                    },
                    "gateway": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "unlimited: gateway host"
                    },
                    "udp": {
                        "type": "boolean",
                        "description": "unlimited: UDP add-on"
                    },
                    "ips": {
                        "type": "integer",
                        "description": "datacenter, isp, dedicated"
                    },
                    "bandwidth_gb": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "datacenter: monthly bandwidth, null when unlimited"
                    },
                    "requests_limit": {
                        "type": "integer",
                        "description": "serp"
                    },
                    "requests_used": {
                        "type": "integer",
                        "description": "serp"
                    }
                }
            },
            "Usage": {
                "type": "object",
                "required": [
                    "product",
                    "granularity",
                    "from",
                    "to",
                    "total",
                    "series"
                ],
                "properties": {
                    "product": {
                        "type": "string"
                    },
                    "granularity": {
                        "type": "string",
                        "enum": [
                            "day",
                            "hour"
                        ]
                    },
                    "from": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "to": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "total": {
                        "type": "object",
                        "description": "`traffic_gb`, or `requests` for serp"
                    },
                    "series": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "timestamp": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "traffic_gb": {
                                    "type": "number"
                                },
                                "requests": {
                                    "type": "integer"
                                }
                            }
                        }
                    }
                }
            },
            "ProxyList": {
                "type": "object",
                "required": [
                    "product",
                    "count",
                    "proxies"
                ],
                "properties": {
                    "product": {
                        "type": "string",
                        "enum": [
                            "datacenter",
                            "isp",
                            "dedicated"
                        ]
                    },
                    "count": {
                        "type": "integer"
                    },
                    "proxies": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "ip": {
                                    "type": "string"
                                },
                                "port": {
                                    "type": "integer",
                                    "description": "isp, dedicated"
                                },
                                "http_port": {
                                    "type": "integer",
                                    "description": "datacenter (3129)"
                                },
                                "socks5_port": {
                                    "type": "integer",
                                    "description": "datacenter (1081)"
                                },
                                "username": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "password": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "country": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "location": {
                                    "type": "string",
                                    "description": "isp"
                                },
                                "expires_at": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "format": "date-time"
                                }
                            }
                        }
                    }
                }
            },
            "WhitelistIp": {
                "type": "object",
                "required": [
                    "ip"
                ],
                "properties": {
                    "ip": {
                        "type": "string"
                    },
                    "label": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "SubUser": {
                "type": "object",
                "required": [
                    "id",
                    "name",
                    "username",
                    "password",
                    "status"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^su_[a-z0-9]+$"
                    },
                    "name": {
                        "type": "string"
                    },
                    "username": {
                        "type": "string"
                    },
                    "password": {
                        "type": "string"
                    },
                    "traffic_limit_gb": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "traffic_used_gb": {
                        "type": "number"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "disabled"
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            }
        }
    }
}
