Przegląd API

Uwierzytelnianie, format żądań, koperta odpowiedzi i pełna mapa endpointów API REST RaxyProxy.

Bazowy URL

https://raxyproxy.com/api/v1

Wszystkie endpointy są wersjonowane pod /api/v1. HTTPS is required.

Uwierzytelnianie

Każde żądanie musi zawierać klucz w nagłówku Authorization w formacie Bearer. Wygeneruj klucz na API Keys page.

Authorization: Bearer raxy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

example.sh

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

Chroń swój klucz

Klucze API zapewniają pełny dostęp — nie umieszczaj w repo. Używaj zmiennych środowiskowych lub menedżera sekretów.

Endpointy

Wszystkie publiczne endpointy v1. Każdy wiersz prowadzi do strony szczegółowej.

Metoda	Ścieżka	Cel
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

Koperta odpowiedzi

Każda pomyślna odpowiedź jest opakowana w standardową kopertę:

response.json

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

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

Błędy

Przy błędzie kod HTTP odzwierciedla kategorię. Treść zawiera klucz error key with a machine-readable code and a human-readable message.

Status	Kod	Znaczenie
`400`	`invalid_request`	Nieprawidłowe żądanie — błędne parametry
`401`	`unauthorized`	Brak lub nieprawidłowy klucz API
`402`	`payment_required`	Niewystarczające środki — doładuj portfel
`403`	`forbidden` / `insufficient_scope`	Zabronione — klucz nie ma scope
`404`	`not_found`	Zasób nie znaleziony
`409`	`conflict`	Konflikt — stan zasobu blokuje operację (np. IP już whitelisted)
`422`	`validation_failed`	Walidacja nieudana — sprawdź obiekt errors
`429`	`rate_limited`	Limit przekroczony — patrz nagłówek Retry-After
`500`	`http_error`	Wewnętrzny błąd serwera
`502`	`provider_error`	Błąd providera upstream — tymczasowy, spróbuj później

error.validation.json

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

Limity żądań

Limity per klucz API, grupowane wg typu. Przy osiągnięciu: 429 + Retry-After.

Grupa	Limit	Endpointy
`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

Specyfikacje czytelne maszynowo do integracji z narzędziami, SDK i AI:

Format	URL	Zastosowanie
OpenAPI 3.0 JSON	`/openapi.json`	Swagger UI, Postman, generatory SDK
Plain text (LLM)	`/llms-api.txt`	ChatGPT, Claude, kontekst Cursor