API Overview

Authentication, request format, response envelope and the full endpoint map of the RaxyProxy REST API.

Base URL

https://raxyproxy.com/api/v1

All endpoints are versioned under /api/v1. HTTPS is required.

Authentication

Every request must include your API key in the Authorization header using Bearer token format. Generate your key on the API Keys page.

Authorization: Bearer raxy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

example.sh

curl https://raxyproxy.com/api/v1/account \
     -H "Authorization: Bearer raxy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Keep your key secret

API keys grant full access to your account — do not commit them to source control. Use environment variables or a secrets manager.

Endpoints

Every public endpoint in v1. Each row links to its own page with detailed schema and code samples.

Method	Path	Purpose
GET	`/account`	Profile, balance, 30d traffic, API key info
GET	`/packages`	List active and suspended packages
GET	`/packages/{id}`	Detailed package (includes proxy password)
GET	`/packages/{id}/proxies`	Generate ready-to-use proxy strings
GET	`/packages/{id}/stats`	Time-series usage (minute / hour / day)
GET	`/packages/{id}/stats/hosts`	Top destinations by traffic
GET	`/packages/{id}/stats/errors`	Recent error events per host / code
POST	`/packages/{id}/rotate-password`	Generate a new proxy password
PATCH	`/packages/{id}/threads`	Update max concurrent connections
PATCH	`/packages/{id}/protocols`	Enable/disable HTTP & SOCKS5
GET	`/packages/{id}/allowed-ips`	List whitelisted client IPs
POST	`/packages/{id}/allowed-ips`	Add an IP to the whitelist
DELETE	`/packages/{id}/allowed-ips/{ip}`	Remove an IP from the whitelist
GET	`/packages/{id}/blocked-hosts`	List domains the package may not reach
PUT	`/packages/{id}/blocked-hosts`	Replace the blocked-hosts list
GET	`/packages/{id}/default-geo`	Default geo applied without per-request params
PUT	`/packages/{id}/default-geo`	Update default geo (countries/states/cities/ASNs…)
POST	`/packages/{id}/top-up`	Add GB to the package using wallet balance
GET	`/packages/{id}/top-ups`	History of top-ups for this package
GET	`/locations/countries`	Available countries for a pool type
GET	`/locations/states`	States within selected countries
GET	`/locations/cities`	Cities within selected countries/states
GET	`/locations/zipcodes`	ZIP codes within selected countries/states
GET	`/locations/asns`	ASNs within selected countries/states/cities

Response Envelope

Every successful response is wrapped in a standard envelope:

response.json

{
  "data": { ... },
  "meta": {
    "version": "v1"
  }
}

The data field contains the actual payload (object or array depending on the endpoint). Paginated endpoints include additional keys inside meta.

Errors

On error the HTTP status code reflects the problem category. The body contains an error key with a machine-readable code and a human-readable message.

Status	Code	Meaning
`400`	`invalid_request`	Bad request — invalid parameters
`401`	`unauthorized`	Missing or invalid API key
`402`	`payment_required`	Insufficient balance — top up your wallet before retrying
`403`	`forbidden` / `insufficient_scope`	Forbidden — key lacks the required scope
`404`	`not_found`	Resource not found
`409`	`conflict`	Conflict — the resource state prevents the operation (e.g. IP already whitelisted)
`422`	`validation_failed`	Validation failed — see the errors object
`429`	`rate_limited`	Rate limit exceeded — see Retry-After header
`500`	`http_error`	Internal server error
`502`	`provider_error`	Upstream provider error — temporary, retry later

error.validation.json

{
  "error": {
    "code":    "validation_failed",
    "message": "Validation failed",
    "errors":  { "threads": ["The threads field must be between 1 and 2000."] }
  },
  "meta": { "version": "v1" }
}

Rate Limits

Limits are per-API-key and grouped by endpoint type. When a limit is hit the server returns 429 and a Retry-After header.

Group	Limit	Endpoints
`api`	120 / min	/account, /packages, /packages/{id}
`stats-api`	60 / min	/stats, /stats/hosts, /stats/errors, /top-ups
`proxies-api`	30 / min	/proxies
`settings-api`	30 / min	all package mutations (rotate-password, allowed-ips, …)
`locations-api`	60 / min	/locations/*
`topup-api`	10 / min	/packages/{id}/top-up

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

OpenAPI / AI Spec

Machine-readable specs are available for integration with tools, SDKs, and AI assistants:

Format	URL	Use case
OpenAPI 3.0 JSON	`/openapi.json`	Swagger UI, Postman, SDK generators
Plain text (LLM)	`/llms-api.txt`	ChatGPT, Claude, Cursor context

← Previous

Scrapy

Account