التوثيق › مرجع API › مرجع Endpoints لـ API

مرجع Endpoints لـ API

مرجع لجميع endpoints الخاصة بـ FourA API مع معلمات request وتنسيقات response.

Base URL

https://eu.api.foura.ai/api

Authentication

يتطلب كل request مفتاح API الخاص بك في header الـ X-API-Key:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

أنشئ مفاتيح API وأدرها في Dashboard. تستخدم المفاتيح البادئة pk_live_.

Response Headers

يحمل كل response من /api/* رأس ارتباط (correlation header) واحدًا:

Header القيمة الوصف
X-Foura-Request-Id UUID معرف فريد مخصص للـ request. يتم إرجاعه مع كل response، بما في ذلك 4xx و 5xx. قم بتسجيله (log) من جانبك.

يربط المعرف نفسه بين معاينة حمولة (payload) الـ request والـ response في Activity Log الخاص بـ Dashboard (يُحتفظ بها لمدة 24 ساعة، وآخر 200 لكل مفتاح)، بحيث يمكنك البحث عن الـ request المحدد لاحقًا وإعادة تشغيله من Activity مباشرة إلى Playground. قم بتضمينه عند الاتصال بالدعم، وسيقوم بتحديد الـ request بدقة في ثوانٍ.

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
...

Endpoints

هل تستخدم هذه endpoints عبر MCP؟ يقوم خادم @fouradata/mcp server بتغليف الـ endpoints الثلاثة كأدوات MCP أصلية (foura_single و foura_proxy و foura_browser) بنفس أشكال المدخلات بالإضافة إلى خيار تفعيل offload_large لمعالجة الـ responses الكبيرة بشكل متوافق مع الـ tokens.

توفر FourA ثلاثة endpoints للـ requests، كل منها مخصص لسيناريوهات مختلفة:

Endpoint الأفضل لـ
POST /single/ طلبات HTTP السريعة، الصفحات الثابتة، و APIs
POST /proxy/ المواقع المحمية مع تدوير تلقائي للـ proxy
POST /browser/ الصفحات التي يتم صيرورتها عبر JavaScript، وتطبيقات SPA

Target URL Restrictions

يتم رفض الأهداف (targets) التي تشير إلى نطاقات IP خاصة أو محلية (loopback) أو محجوزة (RFC 5735، RFC 6598، كتل IPv6 المحجوزة) مع رمز الخطأ 400 قبل أن يغادر الـ request نظام FourA. يتم توجيه أسماء المضيفين (hostnames) وعناوين IP العامة فقط.

{ "error": "Target <ip> resolves to a private/reserved IP" }

Single Request

POST /api/single/

يرسل HTTP request بخصائص شبكة واقعية تشبه المتصفح، دون تشغيل متصفح حقيقي. هذا هو الـ endpoint الأسرع.

Request Body

المعلمة (Parameter) النوع مطلوب الافتراضي الوصف
method string نعم - طريقة HTTP: GET، POST، PUT، PATCH، DELETE، HEAD، OPTIONS
url string نعم - الـ Target URL. استخدم {ts} في أي مكان في الـ URL لإدراج الطابع الزمني الحالي لمنع التخزين المؤقت (cache-busting).
headers [string, string][] لا - الـ headers المخصصة كأزواج [الاسم، القيمة]
unblocker boolean لا false حقن headers متصفح واقعية (User-Agent، Sec-Ch-Ua، Sec-Fetch-*، Accept-Encoding)
timeout_ms number لا 15000 المهلة الإجمالية بالملي ثانية (الحد الأقصى: 120000)
connect_timeout_ms number لا 5000 مهلة الاتصال بالملي ثانية
accept_timeout_ms number لا 5000 مهلة القبول بالملي ثانية (الوقت المستغرق لانتظار قبول الاتصال)
server_response_timeout_ms number لا 15000 مهلة استجابة الخادم بالملي ثانية (الوقت المستغرق لانتظار البايت الأول)
dns_cache_timeout_sec number لا 120 مدة صلاحية (TTL) ذاكرة التخزين المؤقت لـ DNS بالثواني (الحد الأقصى: 240)
followRedirects number لا disabled الحد الأقصى لعمليات إعادة التوجيه التي يجب تتبعها (0-20). اتركه فارغًا للتعطيل.
tryJsonData boolean لا false تحليل جسم الـ response كـ JSON إذا كان ذلك ممكنًا
returnBuffer boolean لا false إرجاع الـ buffer الخام بدلاً من السلسلة النصية التي تم فك ترميزها
data any لا - جسم الـ request (سلسلة نصية أو كائن، يتم تسلسله تلقائيًا إلى JSON)
proxy string لا - عنوان Proxy URL (http أو socks4 أو socks5) أو معرف proxy ID تم إرجاعه بواسطة response سابق
validate object لا - قواعد التحقق من صحة الـ response (انظر أدناه)

Validation Rules

يتيح لك كائن validate تحديد شروط النجاح والفشل. إذا تطابق شرط fail، فسيتم التعامل مع الـ request على أنه فاشل. وإذا تم تعيين شروط accept، فسيتم التعامل مع الـ responses المطابقة فقط على أنها ناجحة.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
الحقل النوع الوصف
validate.status.accept number[] رموز حالة HTTP المقبولة
validate.status.fail number[] رموز حالة HTTP المرفوضة
validate.headers.accept object أزواج مفتاح-قيمة للـ Header التي يجب أن تكون موجودة
validate.headers.fail object أزواج مفتاح-قيمة للـ Header التي تتسبب في الفشل
validate.data.accept string[] السلاسل النصية التي يجب أن تظهر في جسم الـ response
validate.data.fail string[] السلاسل النصية في جسم الـ response التي تتسبب في الفشل

Example

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "unblocker": true,
    "timeout_ms": 10000
  }'

الـ Response:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
الحقل النوع الوصف
status number رمز حالة HTTP من الهدف
headers array كائن واحد لكل قفزة إعادة توجيه (redirect hop). يحتوي كل منها على حقل result مع سطر الحالة بالإضافة إلى كل response header. تعود الـ headers متعددة القيم (Set-Cookie، Link، WWW-Authenticate) كمصفوفات من السلاسل النصية.
data string/object جسم الـ response (يكون JSON إذا كانت قيمة tryJsonData هي true)
total_time number إجمالي وقت الـ request بالثواني
error string رسالة الخطأ في حال فشل الـ request

Proxy Request

POST /api/proxy/

يوجه الـ request الخاص بك عبر proxies دورية مع إعادة المحاولة التلقائية عند الفشل.

Request Body

المعلمة (Parameter) النوع مطلوب الافتراضي الوصف
request object نعم - جسم request فردي (نفس حقول Single Request أعلاه)
timeout_ms number لا 45000 المهلة الإجمالية لجميع المحاولات بالملي ثانية (الحد الأقصى: 120000)
maxTries number لا 5 الحد الأقصى لمحاولات تدوير الـ proxy (الحد الأقصى: 90)
ignoreProxies string[] لا - معرفات Proxy IDs لاستبعادها من التدوير (استخدم المعرفات التي تم إرجاعها بواسطة responses سابقة)

Example

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

الـ Response:

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "a1b2c3",
  "total": 2.341
}
الحقل النوع الوصف
proxy string معرف مشفر للـ proxy المستخدم. أعد استخدامه في Single Request أو Browser Request عن طريق تمريره كحقل proxy، أو تخطاه في Proxy Request التالي عبر ignoreProxies.
total number المدة الزمنية الخارجية الإجمالية بالثواني (عدد عشري float). تشمل اختيار الـ proxy، وإعادة المحاولات، والمحاولة الناجحة. يمثل total_time الـ request الداخلي فقط؛ وتكون قيمة total دائمًا أكبر من أو تساوي total_time.
error string رسالة الخطأ في حال فشل الـ request

يتم أيضًا تضمين جميع حقول استجابة Single Request.

Browser Request

POST /api/browser/

يفتح الـ URL الخاص بك في مثيل متصفح Chrome. يتم تحميل الصفحة، وتنفيذ JavaScript، وتحصل على HTML المصير بالكامل بالإضافة إلى الـ cookie jar.

Request Body

المعلمة (Parameter) النوع مطلوب الافتراضي الوصف
url string نعم - الـ Target URL
headers object لا - الـ headers المخصصة كأزواج مفتاح-قيمة
cookies array لا - ملفات تعريف الارتباط (Cookies) المطلوب تعيينها: [{name, value, domain?}]
userAgent string لا - سلسلة User-Agent مخصصة
proxy string لا - عنوان Proxy URL أو معرف proxy ID تم إرجاعه بواسطة response سابق
timeout_ms number لا 30000 مهلة تحميل الصفحة بالملي ثانية (الحد الأقصى: 120000)
checkStatus number لا - حالة HTTP المتوقعة (يفشل الـ request إذا كانت مختلفة)
checkText string لا - النص الذي يجب أن يظهر في الصفحة المصيرة

Example

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

الـ Response:

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0..."
}
الحقل النوع الوصف
status number رمز حالة HTTP من الهدف
headers object الـ Response headers
body string or object محتوى الصفحة المصير بالكامل. سلسلة نصية HTML عندما يكون content-type هو HTML؛ وكائن عندما ترجع الصفحة JSON ويتم تحليله تلقائيًا.
cookies array كائنات ملفات تعريف الارتباط (cookie) الكاملة من الصفحة. يتضمن كل cookie الحقول name و value و domain و path و expires و httpOnly و secure و sameSite وخصائص الـ cookie الأخرى.
userAgent string الـ User-Agent الخاص بالمتصفح المستخدم
error string رسالة الخطأ في حال فشل الـ request

HTTP Status Codes

الرمز المعنى
200 اكتمل الـ Request (تحقق من الـ status الداخلي لمعرفة استجابة الهدف)
400 جسم request غير صالح، أو معلمات غير صالحة، أو عنوان IP للهدف يقع ضمن نطاق خاص/محجوز
401 مفتاح API مفقود أو غير صالح
429 تم تجاوز حد المعدل (Rate limit)
500 خطأ داخلي في الخادم
503 الخدمة غير متاحة مؤقتًا أو وصلت إلى طاقتها الاستيعابية

Next Steps

آخر تحديث: 1 يوليو 2026
أخطاء API →