{ "openapi": "3.1.0", "info": { "title": "SOAX API", "version": "v1", "description": "Programmatic access to your SOAX account: manage proxy packages, generate connection strings, browse available locations, pull usage analytics, and manage API keys. All endpoints are served over HTTPS and return JSON." }, "paths": { "/v1/api-keys/me": { "get": { "tags": [ "API Keys" ], "summary": "Get information about the authenticated API key", "description": "Retrieve details about the API key used to authenticate the request: its scopes, package restriction, organization ID, and current rate-limit quota. Useful as a first call to verify a key works, and to check remaining rate-limit quota. This endpoint requires no scope — any active key can call it. The key secret is never returned.", "operationId": "get_api_key_me_v1_api_keys_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetApiKeyMeResponse" }, "example": { "id": "3f8a2c1e-5b6d-4e7f-8a9b-0c1d2e3f4a5b", "scopes": [ "proxy:packages:read", "proxy:analytics:read", "account:read", "api-keys:read", "api-keys:write" ], "package_ids": null, "org_id": "0b9c8d7e-6f5a-4b3c-2d1e-0f9a8b7c6d5e", "rate_limit": { "configured_limit": "5/second", "remaining_quota": 4 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/api-keys/": { "get": { "tags": [ "API Keys" ], "summary": "List all API keys for the authenticated customer", "description": "Retrieve all API keys belonging to your organization, including revoked ones. Key secrets are never returned — only metadata. Requires the `api-keys:read` scope.", "operationId": "list_api_keys_v1_api_keys__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ApiKeySummaryResponse" }, "type": "array", "title": "Response List Api Keys V1 Api Keys Get" }, "example": [ { "id": "3f8a2c1e-5b6d-4e7f-8a9b-0c1d2e3f4a5b", "name": "Production backend", "scopes": [ "proxy:packages:read", "proxy:analytics:read", "account:read", "api-keys:read", "api-keys:write" ], "package_ids": null, "status": "active", "created_at": "2026-06-01T09:30:00Z", "updated_at": "2026-06-01T09:30:00Z", "last_used_at": "2026-08-11T08:14:52Z" }, { "id": "7c2d9e0f-1a2b-4c3d-8e9f-a0b1c2d3e4f5", "name": "CI analytics reader", "scopes": [ "proxy:analytics:read" ], "package_ids": [ "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e" ], "status": "revoked", "created_at": "2026-04-20T15:00:00Z", "updated_at": "2026-07-01T10:00:00Z", "last_used_at": "2026-06-30T23:59:01Z" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" } } }, "post": { "tags": [ "API Keys" ], "summary": "Create a new API key for the authenticated customer", "description": "Create a new API key. To prevent privilege escalation, the new key's `scopes` must be a subset of the calling key's scopes, and `package_ids` (if provided) must be a subset of the calling key's package restriction. If `package_ids` is omitted, the new key inherits the calling key's restriction.\n\nThe response includes the plaintext `secret` — this is the **only** time it is ever returned. Store it immediately in a secure location.\n\nRequires the `api-keys:write` scope.", "operationId": "create_api_key_v1_api_keys__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" }, "example": { "name": "CI analytics reader", "scopes": [ "proxy:analytics:read" ], "package_ids": [ "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e" ] } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" }, "example": { "id": "7c2d9e0f-1a2b-4c3d-8e9f-a0b1c2d3e4f5", "name": "CI analytics reader", "scopes": [ "proxy:analytics:read" ], "package_ids": [ "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e" ], "secret": "s_live_Qh1kT3examplenotarealsecretvalueXo9pW2zR8vY5uB0mN4cL7dS6fG1jK", "created_at": "2026-08-11T12:00:00Z" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "description": "A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "error": "Requested scopes exceed the calling key's own scopes" } } } } } } }, "/v1/api-keys/{key_id}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key for the authenticated customer", "description": "Revoke an API key belonging to your organization. Revocation is a soft delete: the key keeps appearing in `GET /v1/api-keys/` with status `revoked`, but any request using it is rejected with 401 from that point on. A key can revoke itself. Revocation cannot be undone — create a new key instead.\n\nRequires the `api-keys:write` scope.", "operationId": "revoke_api_key_v1_api_keys__key_id__delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The API key ID to revoke", "title": "Key Id" }, "description": "The API key ID to revoke" } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages": { "get": { "tags": [ "Packages" ], "summary": "List proxy packages", "description": "Retrieve a paginated list of proxy packages accessible to the API key. If the key is restricted to specific packages, only those are returned. Use cursor-based pagination: pass the `next_cursor` value from one response as the `cursor` parameter of the next request until `has_more` is `false`. Traffic values are in bytes.\n\nRequires the `proxy:packages:read` scope.", "operationId": "list_organization_packages_v1_proxy_packages_get", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor", "description": "Opaque pagination cursor from a previous response's `next_cursor`. Omit for the first page." }, "description": "Opaque pagination cursor from a previous response's `next_cursor`. Omit for the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit", "description": "Number of packages per page (1–100)." }, "description": "Number of packages per page (1–100)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "active", "deleted", "limited", "paused", "suspended" ] }, { "type": "null" } ], "title": "Status", "description": "Filter by package status. A single value only — comma-separated lists are rejected with 400." }, "description": "Filter by package status. A single value only — comma-separated lists are rejected with 400." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyPackagesListResponse" }, "example": { "data": [ { "id": "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e", "name": "Residential - EU scraping", "status": "active", "status_reason": null, "created_at": "2026-03-15T12:00:00Z", "types": [ "wifi" ], "tiers": [ 1, 2, 3 ], "allowed_countries": null, "traffic_limit": 500000000000, "traffic_spent": 120000000000, "traffic_left": 380000000000 }, { "id": "9d8c7b6a-5f4e-4d3c-2b1a-0e9f8d7c6b5a", "name": "Mobile - US", "status": "limited", "status_reason": "traffic_limit_reached", "created_at": "2026-05-02T08:30:00Z", "types": [ "mobile" ], "tiers": [ 1 ], "allowed_countries": [ "us" ], "traffic_limit": 100000000000, "traffic_spent": 100000000000, "traffic_left": 0 } ], "has_more": false, "next_cursor": null } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/proxy/packages/{package_id}": { "get": { "tags": [ "Packages" ], "summary": "Get package details", "description": "Retrieve full configuration for one proxy package: status, network types, tiers, traffic usage (in bytes), the package password used for proxy authentication, connection limits, allowed IPs, port and target rules, and enabled protocols.\n\nIf the API key is restricted to specific packages, requesting a package outside the restriction returns 404 (not 403), so the existence of other packages is not revealed.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_detail_v1_proxy_packages__package_id__get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the proxy package", "title": "Package Id" }, "description": "The ID of the proxy package" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageDetailResponse" }, "example": { "id": "b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e", "name": "Residential - EU scraping", "status": "active", "status_reason": null, "created_at": "2026-03-15T12:00:00Z", "types": [ "wifi" ], "tiers": [ 1, 2, 3 ], "allowed_countries": null, "traffic_limit": 500000000000, "traffic_spent": 120000000000, "traffic_left": 380000000000, "password": "aB3dE5fG7h", "max_connections": 300, "allowed_users": null, "allowed_ips": [ "203.0.113.7" ], "tcp_available_ports": [ 80, 443, "1024-65535" ], "udp_available_ports": [], "tcp_allowed_ports": [], "udp_allowed_ports": [], "ports_mode": "inherit", "tcp_blocked_ports": [ 25 ], "udp_blocked_ports": [], "dns_resolver": "remote", "auth_method": "pwd", "http_allowed": true, "https_allowed": true, "socks5_tcp_allowed": true, "socks5_udp_allowed": false, "allowed_targets": [], "blocked_targets": [], "targets_mode": "inherit", "special_allowed_targets": [], "allowed_target_types": null } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/connection-string": { "get": { "tags": [ "Packages" ], "summary": "Get proxy connection strings", "description": "Build ready-to-use proxy connection strings for a package, with targeting and session rules encoded for you. The returned credentials are used against the proxy gateway (`proxy.soax.com:1337`) — not against this API.\n\nLocation parameters are validated against what the package can actually target: an unavailable country, region, city, ISP, ASN, or ZIP returns 400. `region`, `city`, `isp`, `asn`, and `zip` all require `country` to be set.\n\nRotation and error handling: `rotate-time` and `rotate-requests` are mutually exclusive; `on-error=retry` requires `retries`, and `retries` is only valid with `on-error=retry`; `bind=node` is incompatible with `prefer=lookalike` and `on-error=replace`. When any rotation/error/bind rule is used (or `count` > 1) and no `session` is given, a session ID is generated automatically; with `count` > 1 the session IDs are numbered so each connection string gets its own IP.\n\nFor packages using IP allowlist authentication, rules are encoded in the hostname (HTTPS only), `username` is empty, and `password` is `null`.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_connection_string_v1_proxy_packages__package_id__connection_string_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The ID of the proxy package (UUID format)", "title": "Package Id" }, "description": "The ID of the proxy package (UUID format)" }, { "name": "protocol", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "https", "http", "socks5" ] }, { "type": "null" } ], "title": "Protocol", "description": "Protocol to build the string for. Must be enabled on the package; IP-auth packages support `https` only. If omitted, the `uri` is returned without a scheme prefix." }, "description": "Protocol to build the string for. Must be enabled on the package; IP-auth packages support `https` only. If omitted, the `uri` is returned without a scheme prefix." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Count", "description": "Number of connection strings to return (1–1000). Each gets a numbered session ID so it maps to a distinct IP.", "maximum": 1000 }, "description": "Number of connection strings to return (1–1000). Each gets a numbered session ID so it maps to a distinct IP." }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "residential", "mobile", "any" ] }, { "type": "null" } ], "title": "Network", "description": "Restrict to a network type." }, "description": "Restrict to a network type." }, { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Two-letter ISO country code to target (e.g. `us`). Required when `region`, `city`, `isp`, `asn`, or `zip` is set." }, "description": "Two-letter ISO country code to target (e.g. `us`). Required when `region`, `city`, `isp`, `asn`, or `zip` is set." }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "Region to target. Use codes from the package regions endpoint. Requires `country`." }, "description": "Region to target. Use codes from the package regions endpoint. Requires `country`." }, { "name": "city", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City to target. Use codes from the package cities endpoint. Requires `country`." }, "description": "City to target. Use codes from the package cities endpoint. Requires `country`." }, { "name": "isp", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Isp", "description": "ISP to target. Use codes from the package ISPs endpoint. Requires `country`." }, "description": "ISP to target. Use codes from the package ISPs endpoint. Requires `country`." }, { "name": "asn", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asn", "description": "ASN to target (e.g. `AS7922`). Requires `country` and the ASN targeting feature on your plan." }, "description": "ASN to target (e.g. `AS7922`). Requires `country` and the ASN targeting feature on your plan." }, { "name": "zip", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Zip", "description": "ZIP/postal code to target. Requires `country` and the ZIP targeting feature on your plan." }, "description": "ZIP/postal code to target. Requires `country` and the ZIP targeting feature on your plan." }, { "name": "prefer", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "lookalike" ] }, { "type": "null" } ], "title": "Prefer", "description": "Routing preference. `lookalike` prefers replacement nodes with similar characteristics (same region/ISP) when a node is rotated or replaced." }, "description": "Routing preference. `lookalike` prefers replacement nodes with similar characteristics (same region/ISP) when a node is rotated or replaced." }, { "name": "rotate-time", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rotate-Time", "description": "Rotate to a new IP after this many seconds. Mutually exclusive with `rotate-requests`." }, "description": "Rotate to a new IP after this many seconds. Mutually exclusive with `rotate-requests`." }, { "name": "rotate-requests", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Rotate-Requests", "description": "Rotate to a new IP after this many requests. Mutually exclusive with `rotate-time`." }, "description": "Rotate to a new IP after this many requests. Mutually exclusive with `rotate-time`." }, { "name": "on-error", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "replace", "fail", "retry" ] }, { "type": "null" } ], "title": "On-Error", "description": "What to do when the current node fails: `replace` picks a new node (default behavior), `retry` retries the same node (`retries` required), `fail` returns the error to your client." }, "description": "What to do when the current node fails: `replace` picks a new node (default behavior), `retry` retries the same node (`retries` required), `fail` returns the error to your client." }, { "name": "retries", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Retries", "description": "Number of retry attempts on the same node before replacement. Only valid with `on-error=retry`." }, "description": "Number of retry attempts on the same node before replacement. Only valid with `on-error=retry`." }, { "name": "session", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9]{1,16}$" }, { "type": "null" } ], "title": "Session", "description": "Custom session ID: lowercase letters and digits, up to 16 characters. Requests sharing a session ID keep the same IP. If omitted, a session ID is generated automatically when rotation, error handling, `bind`, or `count` > 1 requires one." }, "description": "Custom session ID: lowercase letters and digits, up to 16 characters. Requests sharing a session ID keep the same IP. If omitted, a session ID is generated automatically when rotation, error handling, `bind`, or `count` > 1 requires one." }, { "name": "bind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "node" ] }, { "type": "null" } ], "title": "Bind", "description": "`node` locks the session to a single node: if the node fails, requests fail instead of being moved to a new IP. Incompatible with `prefer=lookalike` and `on-error=replace`." }, "description": "`node` locks the session to a single node: if the node fails, requests fail instead of being moved to a new IP. Incompatible with `prefer=lookalike` and `on-error=replace`." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyConnectionStringResponse" }, "title": "Response Get Package Connection String V1 Proxy Packages Package Id Connection String Get" }, "example": [ { "uri": "http://country-us-session-k3j9d8f2:aB3dE5fG7h@proxy.soax.com:1337", "username": "country-us-session-k3j9d8f2", "password": "aB3dE5fG7h", "host": "proxy.soax.com", "port": 1337 } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "description": "A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "error": "Cannot specify both 'rotate-time' and 'rotate-requests' simultaneously." } } } } } } }, "/v1/proxy/packages/{package_id}/rotate-password": { "post": { "tags": [ "Packages" ], "summary": "Rotate proxy package password", "description": "Generate a new package password (the 10-character key used to authenticate proxy requests — not the API key). The old password stops working immediately, so update every client that connects through this package. The new plaintext password is returned only in this response.\n\nReturns 400 if the package is deleted or suspended.\n\nRequires the `proxy:packages:write` scope.", "operationId": "rotate_proxy_package_password_v1_proxy_packages__package_id__rotate_password_post", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The package ID", "title": "Package Id" }, "description": "The package ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagePasswordResponse" }, "example": { "password": "xK9mP2qR5t" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available countries for a package", "description": "List the countries this package can route traffic through, with the tier of each country. Use the returned `code` values as the `country` parameter of the connection-string endpoint.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_countries_v1_proxy_packages__package_id__locations_countries_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The package ID", "title": "Package Id" }, "description": "The package ID" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries/{cc}/regions": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available regions for a country in a package", "description": "List regions available in a country for this package. `rank` orders locations by available pool size (1 = largest) and `volume_level` is a coarse 1–3 indicator of relative IP volume (3 = highest, 1 = lowest). Use `code` values as the `region` parameter of the connection-string endpoint.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_country_regions_v1_proxy_packages__package_id__locations_countries__cc__regions_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The package ID", "title": "Package Id" }, "description": "The package ID" }, { "name": "cc", "in": "path", "required": true, "schema": { "type": "string", "description": "The country code", "title": "Cc" }, "description": "The country code" }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "wifi", "mobile", "mix" ] }, { "type": "null" } ], "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package.", "title": "Network" }, "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionsListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries/{cc}/cities": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available cities for a region in a country for a package", "description": "List cities available in a country (optionally narrowed to a region) for this package. Use `code` values as the `city` parameter of the connection-string endpoint.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_cities_v1_proxy_packages__package_id__locations_countries__cc__cities_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The package ID", "title": "Package Id" }, "description": "The package ID" }, { "name": "cc", "in": "path", "required": true, "schema": { "type": "string", "description": "The country code", "title": "Cc" }, "description": "The country code" }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "wifi", "mobile", "mix" ] }, { "type": "null" } ], "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package.", "title": "Network" }, "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package." }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "Narrow results to one region (use a `code` from the regions endpoint)." }, "description": "Narrow results to one region (use a `code` from the regions endpoint)." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitiesListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries/{cc}/isps": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available ISPs for a country in a package", "description": "List ISPs available in a country (optionally narrowed by region and city) for this package. Use `code` values as the `isp` parameter of the connection-string endpoint.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_package_country_isps_v1_proxy_packages__package_id__locations_countries__cc__isps_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The package ID", "title": "Package Id" }, "description": "The package ID" }, { "name": "cc", "in": "path", "required": true, "schema": { "type": "string", "description": "The country code", "title": "Cc" }, "description": "The country code" }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "wifi", "mobile", "mix" ] }, { "type": "null" } ], "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package.", "title": "Network" }, "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package." }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "Narrow results to one region." }, "description": "Narrow results to one region." }, { "name": "city", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "Narrow results to one city." }, "description": "Narrow results to one city." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IspsListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries/{cc}/asns": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available ASNs for a country in a package", "description": "List ASNs available in a country for this package. Use `code` values as the `asn` parameter of the connection-string endpoint.\n\n**Feature gate**: returns 403 if your plan does not include ASN targeting.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_country_asns_v1_proxy_packages__package_id__locations_countries__cc__asns_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the proxy package", "title": "Package Id" }, "description": "The ID of the proxy package" }, { "name": "cc", "in": "path", "required": true, "schema": { "type": "string", "description": "The ISO country code", "title": "Cc" }, "description": "The ISO country code" }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "wifi", "mobile", "mix" ] }, { "type": "null" } ], "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package.", "title": "Network" }, "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package." }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region", "description": "Narrow results to one region." }, "description": "Narrow results to one region." }, { "name": "city", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "Narrow results to one city." }, "description": "Narrow results to one city." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnsListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/packages/{package_id}/locations/countries/{cc}/zip-codes": { "get": { "tags": [ "Packages", "Locations" ], "summary": "Get available zip codes for a country in a package", "description": "List ZIP codes available in a country (optionally narrowed by region and city) for this package. Use `code` values as the `zip` parameter of the connection-string endpoint.\n\n**Feature gate**: returns 403 if your plan does not include ZIP targeting.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_country_city_zip_codes_v1_proxy_packages__package_id__locations_countries__cc__zip_codes_get", "parameters": [ { "name": "package_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the proxy package", "title": "Package Id" }, "description": "The ID of the proxy package" }, { "name": "cc", "in": "path", "required": true, "schema": { "type": "string", "description": "The ISO country code", "title": "Cc" }, "description": "The ISO country code" }, { "name": "network", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "wifi", "mobile", "mix" ] }, { "type": "null" } ], "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package.", "title": "Network" }, "description": "Filter by network type. Valid values are the package's own types (`wifi`, `mobile`, or `mix`); anything else returns 400 listing the networks available on the package." }, { "name": "region", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The region name", "title": "Region" }, "description": "The region name" }, { "name": "city", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The city name", "title": "City" }, "description": "The city name" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipCodesListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Get authenticated customer's account information", "description": "Retrieve your organization's account information: name, status (`active` or `suspended`), current plan identifier, and account creation date.\n\nRequires the `account:read` scope.", "operationId": "get_account_v1_account_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" }, "example": { "name": "Acme Data Inc.", "status": "active", "plan": "business-monthly", "created_at": "2025-11-02T10:15:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" } } } }, "/v1/account/credits": { "get": { "tags": [ "Account" ], "summary": "Get authenticated customer's credit blocks", "description": "List your active credit blocks with their initial and remaining balances and expiry dates. Credits are consumed by proxy traffic according to the tier of the country the traffic routes through.\n\nRequires the `account:read` scope.", "operationId": "get_account_credits_v1_account_credits_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CreditBlockResponse" }, "type": "array", "title": "Response Get Account Credits V1 Account Credits Get" }, "example": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "initial_balance": 1000.0, "balance": 412.5, "effective_date": "2026-08-01T00:00:00Z", "expiry_date": "2026-09-01T00:00:00Z", "status": "active" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" } } } }, "/v1/account/subscription": { "get": { "tags": [ "Account" ], "summary": "Get authenticated customer's active subscription", "description": "Retrieve your active subscription: plan, status, and current billing period. Returns 404 if the account has no active subscription.\n\nRequires the `account:read` scope.", "operationId": "get_account_subscription_v1_account_subscription_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" }, "example": { "id": "e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9", "plan": "Business", "status": "active", "created_at": "2025-11-02T10:20:00Z", "started_at": "2025-11-02T10:20:00Z", "current_billing_period_start_date": "2026-08-02T00:00:00Z", "current_billing_period_end_date": "2026-09-02T00:00:00Z", "end_date": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/proxy/locations/tiers": { "get": { "tags": [ "Locations" ], "summary": "Get available proxy tiers", "description": "List the proxy tiers SOAX offers. Tiers group countries by pool quality and pricing; each country belongs to one tier.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_proxy_tiers_v1_proxy_locations_tiers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TierResponse" }, "type": "array", "title": "Response Get Proxy Tiers V1 Proxy Locations Tiers Get" }, "example": [ { "tier": 1, "name": "Tier 1" }, { "tier": 2, "name": "Tier 2" }, { "tier": 3, "name": "Tier 3" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" } } } }, "/v1/proxy/locations/countries": { "get": { "tags": [ "Locations" ], "summary": "Get available proxy countries", "description": "List every country available on the SOAX network with its tier, regardless of package. To see what a specific package can target, use the package countries endpoint instead.\n\nRequires the `proxy:packages:read` scope.", "operationId": "get_proxy_countries_v1_proxy_locations_countries_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" } } } }, "/v1/proxy/analytics/summary": { "post": { "tags": [ "Analytics" ], "summary": "Get summary statistics for proxy usage", "description": "Retrieve aggregate credits burned and traffic (GB) for the selected date range, compared against the previous period of the same length (`previous_period.to_date` is the day before `from_date`). If the API key is restricted to specific packages, only those packages are included. The date range may span at most 365 days.\n\nRequires the `proxy:analytics:read` scope.", "operationId": "get_summary_v1_proxy_analytics_summary_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryRequest" }, "example": { "from_date": "2026-08-01T00:00:00Z", "to_date": "2026-08-07T23:59:59Z" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryResponse" }, "example": { "selected_period": { "from_date": "2026-08-01T00:00:00Z", "to_date": "2026-08-07T23:59:59Z", "credits_burned": 152.4, "traffic_gb": 61.0 }, "previous_period": { "from_date": "2026-07-25T00:00:00Z", "to_date": "2026-07-31T23:59:59Z", "credits_burned": 133.1, "traffic_gb": 53.2 } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "description": "A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "error": "Date range cannot be more than 1 year" } } } } } } }, "/v1/proxy/analytics/traffic": { "post": { "tags": [ "Analytics" ], "summary": "Get traffic breakdown for proxy usage", "description": "Retrieve traffic (in GB) grouped by a dimension (`package`, `proxy_type`, `tier`, `country`, `domain`, or `ingress_ip`), as a series of interval buckets. When `group_by=package`, keys are package names. The date range may span at most 365 days. If `interval` is omitted it is chosen automatically from the range (< 24 h → `hour`, < 60 days → `day`, otherwise `month`). Explicit intervals are validated: `hour` needs a range of at most 24 hours, `day` between 24 hours and 180 days, `month` at least 60 days.\n\nIf the API key is restricted to specific packages, results (and any `package_ids` filter) are limited to those packages.\n\nRequires the `proxy:analytics:read` scope.", "operationId": "get_traffic_breakdown_v1_proxy_analytics_traffic_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficRequest" }, "example": { "from_date": "2026-08-01T00:00:00Z", "to_date": "2026-08-07T23:59:59Z", "group_by": "country", "interval": "day", "countries": [ "us", "de" ] } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/TrafficResponseItem" }, "type": "array", "title": "Response Get Traffic Breakdown V1 Proxy Analytics Traffic Post" }, "example": [ { "data": [ { "key": "us", "value": 12.41 }, { "key": "de", "value": 3.17 } ] }, { "data": [ { "key": "us", "value": 9.83 }, { "key": "de", "value": 4.02 } ] } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "description": "A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "error": "hour interval requires a date range less than 24 hours" } } } } } } }, "/v1/proxy/analytics/credits-burned": { "post": { "tags": [ "Analytics" ], "summary": "Get credits burned for proxy usage", "description": "Retrieve credits burned per day, broken down by tier. Each item holds one date and a `data` array whose `key` is the tier number (`\"1\"`, `\"2\"`, `\"3\"`) and whose `value` is the credits burned on that tier. The date range may span at most 365 days.\n\nIf the API key is restricted to specific packages, results (and any `package_ids` filter) are limited to those packages.\n\nRequires the `proxy:analytics:read` scope.", "operationId": "get_credits_burned_v1_proxy_analytics_credits_burned_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsRequest" }, "example": { "from_date": "2026-08-01T00:00:00Z", "to_date": "2026-08-03T23:59:59Z" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/CreditsResponseItem" }, "type": "array", "title": "Response Get Credits Burned V1 Proxy Analytics Credits Burned Post" }, "example": [ { "date": "2026-08-01", "data": [ { "key": "1", "value": 100.0 }, { "key": "2", "value": 20.5 } ] }, { "date": "2026-08-02", "data": [ { "key": "1", "value": 84.2 }, { "key": "2", "value": 31.0 } ] }, { "date": "2026-08-03", "data": [ { "key": "1", "value": 91.7 } ] } ] } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "403": { "$ref": "#/components/responses/ForbiddenScope" }, "400": { "description": "A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "error": "Date range cannot be more than 1 year" } } } } } } } }, "components": { "schemas": { "AccountResponse": { "properties": { "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status" }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" } }, "type": "object", "required": [ "name", "status" ], "title": "AccountResponse", "description": "Public response model for customer account information." }, "ApiKeySummaryResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "updated_at": { "type": "string", "format": "date-time", "title": "Updated At" }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Used At" } }, "type": "object", "required": [ "id", "name", "scopes", "package_ids", "status", "created_at", "updated_at", "last_used_at" ], "title": "ApiKeySummaryResponse", "description": "Response schema for a single API key in a list response.\n\nContains key metadata but never exposes the secret or hash." }, "AsnsListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "AsnsListResponse", "description": "Response schema for list of ASNs available in a country for a package.", "example": { "data": [ { "code": "AS1234", "name": "AS1234", "rank": 1, "volume_level": 3 }, { "code": "AS5678", "name": "AS5678", "rank": 2, "volume_level": 2 } ] } }, "CitiesListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "CitiesListResponse", "description": "Response schema for list of cities in a country for a package.", "example": { "data": [ { "code": "NY", "name": "New York", "rank": 1, "volume_level": 3 }, { "code": "LA", "name": "Los Angeles", "rank": 2, "volume_level": 2 } ] } }, "CountriesListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PackageCountryResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "CountriesListResponse", "description": "Response schema for list of countries available in a package.", "example": { "data": [ { "code": "US", "name": "United States", "tier": 1 }, { "code": "GB", "name": "United Kingdom", "tier": 2 } ] } }, "CreateApiKeyRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Human-readable name for the key (shown in the dashboard and key listings)." }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes", "description": "Scopes to grant. Must be a subset of the calling key's own scopes." }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids", "description": "Optional list of package IDs the key is restricted to. Must be a subset of the calling key's own restriction. Omit to inherit the calling key's restriction; `null` on an unrestricted caller creates an unrestricted key." } }, "type": "object", "required": [ "name", "scopes" ], "title": "CreateApiKeyRequest", "description": "Request schema for POST /v1/api-keys endpoint." }, "CreateApiKeyResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids" }, "secret": { "type": "string", "title": "Secret" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "id", "name", "scopes", "package_ids", "secret", "created_at" ], "title": "CreateApiKeyResponse", "description": "Response schema for POST /v1/api-keys endpoint.\n\nIncludes the plaintext secret, which is only revealed at creation time\nand can never be retrieved again. The secret should be immediately\nstored by the client in a secure location." }, "CreditBlockResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "initial_balance": { "type": "number", "title": "Initial Balance" }, "balance": { "type": "number", "title": "Balance" }, "effective_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Effective Date" }, "expiry_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expiry Date" }, "status": { "type": "string", "title": "Status" } }, "type": "object", "required": [ "id", "initial_balance", "balance", "status" ], "title": "CreditBlockResponse", "description": "Public response model for a single credit block." }, "CreditsDataPoint": { "properties": { "key": { "type": "string", "title": "Key" }, "value": { "type": "number", "title": "Value" } }, "type": "object", "required": [ "key", "value" ], "title": "CreditsDataPoint", "description": "Single data point in credits breakdown." }, "CreditsRequest": { "properties": { "from_date": { "type": "string", "format": "date-time", "title": "From Date", "description": "Start of the query range (ISO 8601)." }, "to_date": { "type": "string", "format": "date-time", "title": "To Date", "description": "End of the query range (ISO 8601). At most 365 days after `from_date`." }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids", "description": "Restrict results to these package IDs." } }, "type": "object", "required": [ "from_date", "to_date" ], "title": "CreditsRequest", "description": "Request model for credits burned breakdown analysis." }, "CreditsResponseItem": { "properties": { "date": { "type": "string", "title": "Date" }, "data": { "items": { "$ref": "#/components/schemas/CreditsDataPoint" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "date", "data" ], "title": "CreditsResponseItem", "description": "Response item for credits burned breakdown analysis." }, "GetApiKeyMeResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "scopes": { "items": { "type": "string" }, "type": "array", "title": "Scopes" }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids" }, "org_id": { "type": "string", "title": "Org Id" }, "rate_limit": { "$ref": "#/components/schemas/RateLimitInfo" } }, "type": "object", "required": [ "id", "scopes", "package_ids", "org_id", "rate_limit" ], "title": "GetApiKeyMeResponse", "description": "Response schema for GET /v1/api-keys/me endpoint." }, "GroupBy": { "type": "string", "enum": [ "package", "proxy_type", "tier", "country", "domain", "ingress_ip" ], "title": "GroupBy", "description": "Allowed grouping dimensions for analytics queries." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Interval": { "type": "string", "enum": [ "hour", "day", "month" ], "title": "Interval", "description": "Allowed time intervals for analytics aggregation." }, "IspsListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "IspsListResponse", "description": "Response schema for list of ISPs available in a country for a package.", "example": { "data": [ { "code": "CM", "name": "Comcast", "rank": 1, "volume_level": 3 }, { "code": "VZ", "name": "Verizon", "rank": 2, "volume_level": 2 } ] } }, "LocationResponse": { "properties": { "code": { "type": "string", "title": "Code" }, "name": { "type": "string", "title": "Name" }, "rank": { "type": "integer", "title": "Rank", "description": "Position when locations are ordered by available pool size (1 = largest)." }, "volume_level": { "type": "integer", "title": "Volume Level", "minimum": 1, "maximum": 3, "description": "Coarse 1–3 indicator of relative IP volume: 3 = highest, 1 = lowest." } }, "type": "object", "required": [ "code", "name", "rank", "volume_level" ], "title": "LocationResponse", "description": "Response schema for a location result.", "example": { "code": "as1234", "name": "AS1234", "rank": 1, "volume_level": 3 } }, "PackageCountryResponse": { "properties": { "code": { "type": "string", "title": "Code" }, "name": { "type": "string", "title": "Name" }, "tier": { "type": "integer", "title": "Tier" } }, "type": "object", "required": [ "code", "name", "tier" ], "title": "PackageCountryResponse", "description": "Response schema for a country with available locations in a package.", "example": { "code": "US", "name": "United States", "tier": 1 } }, "PackageDetailResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status", "description": "Display status: `active`, `paused` (manually paused), `limited` (traffic limit reached), `suspended`, or `deleted`." }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Reason", "description": "Why the package is not active: `user_paused`, `traffic_limit_reached`, `out_of_credits`, `account_suspended`, `plan_limit_exceeded`, or `null`." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "types": { "items": { "$ref": "#/components/schemas/ProxyPackageType" }, "type": "array", "title": "Types", "default": [] }, "tiers": { "items": { "type": "integer" }, "type": "array", "title": "Tiers", "default": [] }, "allowed_countries": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Countries" }, "traffic_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Limit" }, "traffic_spent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Spent" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "max_connections": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Max Connections" }, "allowed_users": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Users" }, "allowed_ips": { "items": { "type": "string" }, "type": "array", "title": "Allowed Ips" }, "tcp_available_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Tcp Available Ports" }, "udp_available_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Udp Available Ports" }, "tcp_allowed_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Tcp Allowed Ports" }, "udp_allowed_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Udp Allowed Ports" }, "ports_mode": { "type": "string", "title": "Ports Mode" }, "tcp_blocked_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Tcp Blocked Ports" }, "udp_blocked_ports": { "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": "array", "title": "Udp Blocked Ports" }, "dns_resolver": { "type": "string", "title": "Dns Resolver" }, "auth_method": { "type": "string", "title": "Auth Method" }, "http_allowed": { "type": "boolean", "title": "Http Allowed", "default": true }, "https_allowed": { "type": "boolean", "title": "Https Allowed", "default": true }, "socks5_tcp_allowed": { "type": "boolean", "title": "Socks5 Tcp Allowed", "default": true }, "socks5_udp_allowed": { "type": "boolean", "title": "Socks5 Udp Allowed", "default": true }, "allowed_targets": { "items": { "type": "string" }, "type": "array", "title": "Allowed Targets" }, "blocked_targets": { "items": { "type": "string" }, "type": "array", "title": "Blocked Targets" }, "targets_mode": { "type": "string", "title": "Targets Mode" }, "special_allowed_targets": { "items": { "type": "string" }, "type": "array", "title": "Special Allowed Targets" }, "allowed_target_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Target Types" }, "traffic_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Left", "description": "Calculate the remaining traffic for the package.", "readOnly": true } }, "type": "object", "required": [ "id", "name", "status", "ports_mode", "dns_resolver", "auth_method", "targets_mode", "traffic_left" ], "title": "PackageDetailResponse", "description": "Response model for package detail endpoint (GET /v1/proxy/packages/{package_id})." }, "PackagePasswordResponse": { "properties": { "password": { "type": "string", "title": "Password", "description": "The newly generated plaintext password/key" } }, "type": "object", "required": [ "password" ], "title": "PackagePasswordResponse", "description": "Response schema for password rotation endpoint.", "example": { "password": "a1b2c3d4e5" } }, "PeriodSummary": { "properties": { "from_date": { "type": "string", "format": "date-time", "title": "From Date", "description": "Start date of the period" }, "to_date": { "type": "string", "format": "date-time", "title": "To Date", "description": "End date of the period" }, "credits_burned": { "type": "number", "title": "Credits Burned", "description": "Total credits burned in the period" }, "traffic_gb": { "type": "number", "title": "Traffic Gb", "description": "Total traffic spent in GB" } }, "type": "object", "required": [ "from_date", "to_date", "credits_burned", "traffic_gb" ], "title": "PeriodSummary", "description": "Summary data for a single period." }, "ProxyConnectionStringResponse": { "properties": { "uri": { "type": "string", "title": "Uri" }, "username": { "type": "string", "title": "Username" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Password" }, "host": { "type": "string", "title": "Host" }, "port": { "type": "integer", "title": "Port" } }, "type": "object", "required": [ "uri", "username", "host", "port" ], "title": "ProxyConnectionStringResponse", "description": "Response model for a single proxy connection string in v1 API." }, "ProxyPackageResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "status": { "type": "string", "title": "Status", "description": "Display status: `active`, `paused` (manually paused), `limited` (traffic limit reached), `suspended`, or `deleted`." }, "status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Reason", "description": "Why the package is not active: `user_paused`, `traffic_limit_reached`, `out_of_credits`, `account_suspended`, `plan_limit_exceeded`, or `null`." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Created At" }, "types": { "items": { "$ref": "#/components/schemas/ProxyPackageType" }, "type": "array", "title": "Types", "default": [] }, "tiers": { "items": { "type": "integer" }, "type": "array", "title": "Tiers", "default": [] }, "allowed_countries": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Allowed Countries" }, "traffic_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Limit" }, "traffic_spent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Spent" }, "traffic_left": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Traffic Left", "description": "Calculate the remaining traffic for the package.", "readOnly": true } }, "type": "object", "required": [ "id", "name", "status", "traffic_left" ], "title": "ProxyPackageResponse", "description": "Public response model for a single proxy package." }, "ProxyPackageType": { "type": "string", "enum": [ "mix", "wifi", "mobile" ], "title": "ProxyPackageType" }, "ProxyPackagesListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProxyPackageResponse" }, "type": "array", "title": "Data" }, "has_more": { "type": "boolean", "title": "Has More" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data", "has_more" ], "title": "ProxyPackagesListResponse", "description": "Public response model for listing proxy packages with pagination." }, "RateLimitInfo": { "properties": { "configured_limit": { "type": "string", "title": "Configured Limit" }, "remaining_quota": { "type": "integer", "title": "Remaining Quota" } }, "type": "object", "required": [ "configured_limit", "remaining_quota" ], "title": "RateLimitInfo", "description": "Rate limit information for an API key." }, "RegionsListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "RegionsListResponse", "description": "Response schema for list of regions in a country.", "example": { "data": [ { "code": "ca", "name": "California", "rank": 1, "volume_level": 3 }, { "code": "tx", "name": "Texas", "rank": 2, "volume_level": 2 } ] } }, "SubscriptionResponse": { "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Plan" }, "status": { "type": "string", "title": "Status" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" }, "started_at": { "type": "string", "format": "date-time", "title": "Started At" }, "current_billing_period_start_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Current Billing Period Start Date" }, "current_billing_period_end_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Current Billing Period End Date" }, "end_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, "type": "object", "required": [ "status", "created_at", "started_at" ], "title": "SubscriptionResponse", "description": "Public response model for customer subscription information." }, "SummaryRequest": { "properties": { "from_date": { "type": "string", "format": "date-time", "title": "From Date", "description": "Start date for the query range" }, "to_date": { "type": "string", "format": "date-time", "title": "To Date", "description": "End date for the query range. At most 365 days after `from_date`." } }, "type": "object", "required": [ "from_date", "to_date" ], "title": "SummaryRequest", "description": "Request model for summary statistics query." }, "SummaryResponse": { "properties": { "selected_period": { "$ref": "#/components/schemas/PeriodSummary", "description": "Stats for the selected period" }, "previous_period": { "$ref": "#/components/schemas/PeriodSummary", "description": "Stats for the previous period (for comparison)" } }, "type": "object", "required": [ "selected_period", "previous_period" ], "title": "SummaryResponse", "description": "Response schema for summary endpoint." }, "TierResponse": { "properties": { "tier": { "type": "integer", "title": "Tier" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "tier", "name" ], "title": "TierResponse", "description": "Response schema for a proxy tier.", "example": { "name": "Tier 1", "tier": 1 } }, "TrafficDataPoint": { "properties": { "key": { "type": "string", "title": "Key" }, "value": { "type": "number", "title": "Value" } }, "type": "object", "required": [ "key", "value" ], "title": "TrafficDataPoint", "description": "Single data point in traffic breakdown." }, "TrafficRequest": { "properties": { "from_date": { "type": "string", "format": "date-time", "title": "From Date", "description": "Start of the query range (ISO 8601)." }, "to_date": { "type": "string", "format": "date-time", "title": "To Date", "description": "End of the query range (ISO 8601). At most 365 days after `from_date`." }, "group_by": { "$ref": "#/components/schemas/GroupBy", "default": "package" }, "interval": { "anyOf": [ { "$ref": "#/components/schemas/Interval" }, { "type": "null" } ], "description": "Bucket size for the series. Auto-selected from the range when omitted (< 24 h → hour, < 60 days → day, otherwise month)." }, "package_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Package Ids", "description": "Restrict results to these package IDs." }, "network_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Network Types", "description": "Restrict results to network types: `residential` and/or `mobile`." }, "tiers": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Tiers", "description": "Restrict results to tiers (1, 2, or 3)." }, "countries": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Countries", "description": "Restrict results to these ISO country codes." }, "target_addresses": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Target Addresses", "description": "Restrict results to traffic sent to these domains." } }, "type": "object", "required": [ "from_date", "to_date" ], "title": "TrafficRequest", "description": "Request model for traffic breakdown analysis." }, "TrafficResponseItem": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TrafficDataPoint" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "TrafficResponseItem", "description": "Response item for traffic breakdown analysis." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ZipCodesListResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "ZipCodesListResponse", "description": "Response schema for list of zip codes available in a country/city for a package.", "example": { "data": [ { "code": "10001", "name": "10001", "rank": 1, "volume_level": 3 }, { "code": "10002", "name": "10002", "rank": 2, "volume_level": 2 } ] } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key secret (starts with `s_live_`). Create keys in the dashboard under **Settings → API keys**, or via `POST /v1/api-keys/`. Send it as `Authorization: Bearer `." } }, "responses": { "Unauthorized": { "description": "Missing, invalid, or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Invalid API key" } } } }, "ForbiddenScope": { "description": "The API key does not carry the scope this endpoint requires.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Missing required scope: proxy:packages:read" } } } }, "NotFound": { "description": "The resource does not exist, belongs to another organization, or is outside the API key's package restriction.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Package not found" } } } }, "BadRequest": { "description": "A parameter value is invalid. Depending on which validation layer rejects the request, the message is under `detail` (endpoint-level checks) or `error` (service-level checks); read `detail ?? error`. The message names the parameter and lists valid values where applicable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "error": { "type": "string" } } }, "example": { "detail": "Invalid status value: archived. Valid values are: active, deleted, limited, paused, suspended" } } } }, "RateLimited": { "description": "Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "example": { "error": "Rate limit exceeded: 5 per 1 second" } } } } } }, "servers": [ { "url": "https://api.platform.soax.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "API Keys", "description": "Self-service management of the API keys used to authenticate with this API." }, { "name": "Packages", "description": "Read proxy packages, build proxy connection strings, and rotate package passwords." }, { "name": "Locations", "description": "Location reference data: tiers, countries, regions, cities, ISPs, ASNs, and ZIP codes." }, { "name": "Account", "description": "Read-only account, credit, and subscription information." }, { "name": "Analytics", "description": "Usage analytics for your proxy packages." } ] }