API 概览

RaxyProxy REST API 的身份验证、请求格式、响应信封以及完整端点地图。

基础 URL

https://raxyproxy.com/api/v1

所有端点均在 /api/v1. HTTPS is required.

身份验证

每个请求都必须在 Authorization 标头中以 Bearer 令牌格式包含 API 密钥。在 API Keys page.

Authorization: Bearer raxy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

example.sh

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

保持密钥保密

API 密钥授予对账户的完全访问权限 — 请勿提交到版本控制。请使用环境变量或密钥管理器。

端点

v1 中所有公开端点。每行链接到详细页面。

方法	路径	用途
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.json

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

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

错误

错误时 HTTP 状态码反映类别。响应体包含 error key with a machine-readable code and a human-readable message.

状态	代码	含义
`400`	`invalid_request`	错误请求 — 参数无效
`401`	`unauthorized`	API 密钥缺失或无效
`402`	`payment_required`	余额不足 — 请先充值
`403`	`forbidden` / `insufficient_scope`	禁止 — 密钥缺少 scope
`404`	`not_found`	资源未找到
`409`	`conflict`	冲突 — 状态阻止操作（例如 IP 已在白名单）
`422`	`validation_failed`	验证失败 — 查看 errors 对象
`429`	`rate_limited`	超出速率限制 — 查看 Retry-After 标头
`500`	`http_error`	内部服务器错误
`502`	`provider_error`	上游提供商错误 — 临时性，请稍后重试

error.validation.json

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

速率限制

每个 API 密钥按端点分组限制。达到限制时返回 429 + Retry-After。

组	限制	端点
`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 规范

可与工具、SDK 和 AI 助手集成的机器可读规范：

格式	URL	使用场景
OpenAPI 3.0 JSON	`/openapi.json`	Swagger UI、Postman、SDK 生成器
Plain text (LLM)	`/llms-api.txt`	ChatGPT、Claude、Cursor 上下文

← 上一页

Scrapy

账户