نظرة عامة على API

المصادقة وتنسيق الطلب وغلاف الاستجابة وخريطة كاملة لنقاط نهاية RaxyProxy REST API.

عنوان URL الأساسي

https://raxyproxy.com/api/v1

جميع نقاط النهاية مُصدَّرة تحت /api/v1. HTTPS is required.

المصادقة

يجب أن يتضمن كل طلب مفتاح API في رأس Authorization بصيغة Bearer. أنشئ مفتاحك من 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

الحساب