AY-ROBOTSAI Teleoperation
Sign Up

مرجع API

يقع REST API الخاص بـ AY-Robots تحت https://www.ay-robots.com/api ويتحدث JSON في الاتجاهين. توثّق هذه الصفحة المصادقة، واتفاقيات الاستجابة، وكل نقطة نهاية، مع توثيق كامل للمعاملات للمسارات الأكثر احتمالاً أن تستدعيها برمجياً.

آخر تحديث 2026-08-09

المصادقة

تتطلب كل نقطة نهاية مصادقة ما لم تكن مُدرَجة في قسم Public. يقبل API نوعين من بيانات الاعتماد، وكلاهما يصل بالطريقة نفسها: إما كـ session cookie ترسلها لوحة التحكم أصلاً، أو كـ Authorization header برمز Bearer.

الطريقةكيف تعملاستخدمها لـ
جلسة المتصفحرمز جلسة Supabase لحسابك المسجَّل دخوله، يُرسَل كـ cookie أو كرمز Bearerلوحة التحكم نفسها والتجارب السريعة من سياق متصفح مُصادَق عليه
مفتاح APIمفتاح بالبادئة ayr_live_، يُنشأ في /dashboard/settings ويُرسَل كرمز Bearerالبرامج النصية، الخوادم، CI، وكل ما يجب ألا يعتمد على تسجيل دخول في المتصفح
MCPخادم MCP المُستضاف على https://www.ay-robots.com/api/mcp (Streamable HTTP)وكلاء LLM والأدوات التي تتحدث Model Context Protocol
bash
curl https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here'
المصادقة بمفتاح API

تُنشأ مفاتيح API وتُلغى في /dashboard/settings. عاملها مثل كلمات المرور: احتفظ بها على جانب الخادم، وارفع بديلاً قبل إلغاء المفتاح القديم عند التدوير. إن كنت تستخدم CLI سطح المكتب، فيمكنه أيضاً إظهار المنصة كخادم MCP محلي بالأمر: ay-robots mcp.

الاستجابات بصيغة JSON. تستخدم الأخطاء شكلاً متسقاً: كائن JSON بحقل error واحد يحتوي رسالة مقروءة للبشر، مُسلَّم برمز حالة 4xx أو 5xx مناسب. تعيد استجابات النجاح المورد مباشرة؛ تُغلِّف بعض نقاط النهاية القوائم في حقل مُسمّى، وهو ما تُظهره الأمثلة أدناه حيث يهم ذلك.

نقاط نهاية المصادقة

البنية الأساسية للحساب والملف الشخصي. تستخدمها لوحة التحكم نفسها بشكل أساسي، لكنها تعمل مع أي بيانات اعتماد صالحة.

GET/api/auth/profileرمز جلسة Bearer أو مفتاح API

يعيد ملف المستخدم المُصادَق عليه.

POST/api/auth/profileرمز جلسة Bearer أو مفتاح API

يحدّث حقول الملف الشخصي مثل الاسم المعروض وتفضيلات الإشعارات.

POST/api/auth/syncرمز جلسة Bearer

يزامن مستخدم مصادقة Supabase مع سجل مستخدم المنصة.

GET/api/auth/check-onboardingرمز جلسة Bearer

يُبلِّغ عمّا إذا كان المستخدم المُصادَق عليه قد أكمل onboarding.

POST/api/auth/avatarرمز جلسة Bearer

يرفع صورة رمزية جديدة للمستخدم المُصادَق عليه.

نقاط نهاية العميل

كل ما يديره صاحب الروبوتات: الروبوتات المسجَّلة، الملف الشخصي للعميل، مجموعات البيانات، الفواتير، وإحصاءات لوحة التحكم.

GET/api/client/robotsرمز جلسة Bearer أو مفتاح API (دور العميل)

يسرد الروبوتات المسجَّلة من قِبل العميل المُصادَق عليه، الأحدث أولاً، حتى 50 إدخالاً. الأختام الزمنية بصيغة ISO 8601؛ يبقى last_online وlast_heartbeat فارغَين (null) حتى يتصل الروبوت مرة واحدة.

Request
curl https://www.ay-robots.com/api/client/robots \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
[
  {
    "id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
    "name": "Lab SO-100",
    "robot_type": "SO-100",
    "status": "AVAILABLE",
    "control_url": "wss://robots.example.com/so100/control",
    "stream_url": "https://robots.example.com/so100/stream",
    "hardware_id": "board:local:usb-1",
    "last_online": "2026-08-09T10:12:00.000Z",
    "last_heartbeat": "2026-08-09T10:12:00.000Z",
    "total_hours": 12.5,
    "tags": ["lab"],
    "notes": null,
    "created_at": "2026-07-01T09:00:00.000Z"
  }
]
POST/api/client/robotsرمز جلسة Bearer أو مفتاح API (دور العميل)

يسجّل روبوتاً جديداً ويعيد id الخاص به. يمكن أن ينتمي hardware id للوحة محرك واحدة إلى روبوت واحد فقط؛ يُرفض التعارض برمز حالة 409.

GET/api/client/profileرمز جلسة Bearer أو مفتاح API (دور العميل)

يعيد الملف الشخصي للعميل المُصادَق عليه.

PATCH/api/client/profileرمز جلسة Bearer أو مفتاح API (دور العميل)

يحدّث حقول الملف الشخصي للعميل.

GET/api/client/datasetsرمز جلسة Bearer أو مفتاح API (دور العميل)

يسرد مجموعات البيانات السحابية للعميل مع عدد episodes وأحجامها.

GET/api/client/invoicesرمز جلسة Bearer أو مفتاح API (دور العميل)

يسرد فواتير العميل الشهرية.

GET/api/client/statsرمز جلسة Bearer أو مفتاح API (دور العميل)

يعيد إحصاءات الاستخدام للوحة تحكم العميل.

نقاط نهاية المشغل

جانب المشغل: الملف الشخصي والتوفر، والاعتمادات، والجدولة، وإحصاءات الأرباح.

GET/api/operator/profileرمز جلسة Bearer أو مفتاح API (دور المشغل)

يعيد الملف الشخصي للمشغل المُصادَق عليه.

POST/api/operator/profileرمز جلسة Bearer أو مفتاح API (دور المشغل)

ينشئ أو يحدّث الملف الشخصي للمشغل.

GET/api/operator/available-robotsرمز جلسة Bearer أو مفتاح API (دور المشغل)

يسرد الروبوتات المتاحة حالياً والمطابقة لاعتمادات المشغل.

GET/api/operator/certificationsرمز جلسة Bearer أو مفتاح API (دور المشغل)

يسرد طلبات اعتماد المشغل وحالتها.

POST/api/operator/certificationsرمز جلسة Bearer أو مفتاح API (دور المشغل)

يطلب اعتماداً لنوع روبوت.

GET/api/operator/scheduleرمز جلسة Bearer أو مفتاح API (دور المشغل)

يعيد جدول توفر المشغل الأسبوعي.

POST/api/operator/scheduleرمز جلسة Bearer أو مفتاح API (دور المشغل)

يحدّث جدول التوفر الأسبوعي.

GET/api/operator/availabilityرمز جلسة Bearer أو مفتاح API (دور المشغل)

يعيد توفر المشغل الحالي.

GET/api/operator/statsرمز جلسة Bearer أو مفتاح API (دور المشغل)

يعيد إحصاءات الأرباح والجلسات للوحة تحكم المشغل.

الجلسات

الجلسات هي المورد الأساسي للمنصة: الجلسة الواحدة هي ارتباط تشغيل عن بُعد مستمر واحد بين مشغل وروبوت. تنتقل حالة الجلسة عبر PENDING وACTIVE وPAUSED وCOMPLETED وCANCELLED.

GET/api/sessionsرمز جلسة Bearer أو مفتاح API

يسرد الجلسات للمستخدم المُصادَق عليه. يرى المشغلون الجلسات التي شغّلوها؛ يرى العملاء الجلسات على روبوتاتهم. تختلف مجموعة الحقول قليلاً بين الرأيين: يتضمن رأي العميل episodes_collected وdata_collected_mb، ويتضمن رأي المشغل operator_earnings_cents.

NameInTypeDescription
statusquerystringاختياري. صفّي حسب حالة الجلسة، مثلاً ACTIVE أو COMPLETED. اتركه لعرض الكل.
limitquerynumberاختياري. حجم الصفحة، الافتراضي 50، الحد الأقصى 100.
offsetquerynumberاختياري. إزاحة الترقيم، الافتراضي 0.
Request
curl 'https://www.ay-robots.com/api/sessions?status=COMPLETED&limit=10' \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
{
  "sessions": [
    {
      "id": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
      "status": "COMPLETED",
      "started_at": "2026-08-08T14:00:12.000Z",
      "ended_at": "2026-08-08T14:47:31.000Z",
      "duration_minutes": 47,
      "client_charge_cents": 1175,
      "episodes_collected": 23,
      "data_collected_mb": 210.4,
      "rating": 5,
      "created_at": "2026-08-08T13:59:58.000Z",
      "robot_id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
      "robot_name": "Lab SO-100",
      "robot_type": "SO-100",
      "operator_name": "Jane D."
    }
  ]
}
POST/api/sessionsرمز جلسة Bearer أو مفتاح API (دور المشغل)

يبدأ جلسة تشغيل عن بُعد على روبوت متاح. يتطلب دور المشغل: لا يمكن للعملاء بدء جلسات. يمكن لمشغل واحد الاحتفاظ بحد أقصى جلسة واحدة ACTIVE أو PAUSED في وقت واحد، ويجب أن يكون الروبوت حالياً بحالة AVAILABLE. عند البدء الفوري يتحول الروبوت إلى IN_SESSION ويُخطَر العميل.

NameInTypeDescription
robotIdbodystringمطلوب. id الروبوت المراد تشغيله. يجب أن يكون الروبوت AVAILABLE.
operatorIdbodystringاختياري. id صريح للمشغل؛ افتراضياً المشغل المُصادَق عليه.
scheduledForbodystring (ISO 8601)اختياري. يجدول الجلسة لوقت مستقبلي بدلاً من بدئها فوراً.
Request
curl -X POST https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"robotId": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11"}'
Response
{
  "sessionId": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
  "status": "ACTIVE"
}
GET/api/sessions/[id]رمز جلسة Bearer أو مفتاح API

يعيد جلسة واحدة مع تفاصيلها.

PATCH/api/sessions/[id]رمز جلسة Bearer أو مفتاح API

يحدّث دورة حياة الجلسة: إيقاف مؤقت، استئناف، إنهاء، وإجراءات ذات صلة.

POST/api/sessions/[id]/extendرمز جلسة Bearer أو مفتاح API (العميل، مالك الجلسة)

يطلب تمديد جلسة. لا يمكن استدعاء هذا إلا من العميل مالك الجلسة، ويجب أن تكون الجلسة ACTIVE. يُسجَّل الطلب كحدث جلسة ويتلقى المشغل إشعاراً؛ يحدث التمديد نفسه عندما يتصرف المشغل بناءً عليه.

NameInTypeDescription
idpathstringid الجلسة.
additionalMinutesbodynumberمدة التمديد المطلوبة بالدقائق.
Request
curl -X POST https://www.ay-robots.com/api/sessions/6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30/extend \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"additionalMinutes": 30}'
Response
{
  "message": "Extension request sent to operator"
}
GET/api/sessions/[id]/messagesرمز جلسة Bearer أو مفتاح API

يسرد رسائل دردشة جلسة ما.

POST/api/sessions/[id]/messagesرمز جلسة Bearer أو مفتاح API

يرسل رسالة دردشة في جلسة.

POST/api/sessions/[id]/rateرمز جلسة Bearer أو مفتاح API (العميل)

يقيّم جلسة مكتملة على مقياس من 1 إلى 5 نجوم، بتعليق اختياري.

POST/api/sessions/exportرمز جلسة Bearer أو مفتاح API

يصدّر بيانات الجلسة.

المدفوعات

كل حركة أموال تمر عبر Stripe. تستخدم فوترة العملاء عميل Stripe (customer) بطريقة دفع محفوظة؛ تستخدم مدفوعات المشغلين Stripe Connect. المنصة نفسها لا تخزّن أبداً بيانات البطاقات أو البنك.

POST/api/stripe/customerرمز جلسة Bearer (دور العميل)

ينشئ أو يعيد عميل Stripe المستخدَم لفوترة العميل.

GET/api/stripe/connectرمز جلسة Bearer (دور المشغل)

يعيد حالة حساب Stripe Connect الخاص بالمشغل.

POST/api/stripe/connectرمز جلسة Bearer (دور المشغل)

يبدأ onboarding الخاص بـ Stripe Connect لمدفوعات المشغل.

POST/api/stripe/setup-intentرمز جلسة Bearer (دور العميل)

ينشئ SetupIntent من Stripe لحفظ طريقة دفع.

POST/api/stripe/portalرمز جلسة Bearer (دور العميل)

ينشئ جلسة Stripe billing portal لإدارة طرق الدفع والفواتير.

GET/api/stripe/payoutرمز جلسة Bearer (دور المشغل)

يعيد معلومات الدفع للمشغل المُصادَق عليه.

POST/api/stripe/payoutرمز جلسة Bearer (دور المشغل)

يطلب دفع الأرباح المتراكمة. الحد الأدنى للدفع هو 10.00 EUR.

POST/api/stripe/webhookتوقيع webhook من Stripe

يستقبل أحداث webhook من Stripe. يستدعيه Stripe، لا عملاء API.

نقاط النهاية العامة

لا تتطلب نقاط النهاية هذه أي مصادقة. من الآمن استدعاؤها من المراقبة، أو صفحات التسويق، أو مسبار حالة.

GET/api/health

فحص سلامة للـ API واتصال قاعدة بياناته. يعيد 200 عندما يكون كلاهما بخير؛ إن فشل فحص قاعدة البيانات، يُعاد الشكل نفسه مع تعيين status وdb إلى error وحالة HTTP 503.

Request
curl https://www.ay-robots.com/api/health
Response
{
  "status": "ok",
  "db": "ok",
  "timestamp": "2026-08-09T10:12:00.000Z"
}
GET/api/robots/[id]

يعيد معلومات عامة عن طراز روبوت مدعوم.

GET/api/public/pricing

يعيد خطط التسعير العامة الحالية.

POST/api/contact

يرسل رسالة نموذج تواصل. تُخزَّن الرسالة أولاً ثم تُسلَّم عبر البريد الإلكتروني، لذا لا يفقدها انقطاع مؤقت في البريد: في تلك الحالة تُبلِّغ الاستجابة بـ stored true وdelivered false، وتُعاد محاولة التسليم تشغيلياً.

NameInTypeDescription
namebodystringمطلوب. اسمك.
emailbodystringمطلوب. عنوان بريد إلكتروني صالح للرد.
categorybodystringمطلوب. واحدة من: General Inquiry, Bug Report, Feature Request, Sales & Pricing, Partnership, Career/Jobs, Technical Support, Billing & Payments, Press & Media, Other.
subjectbodystringمطلوب. سطر موضوع قصير.
messagebodystringمطلوب. نص الرسالة.
Request
curl -X POST https://www.ay-robots.com/api/contact \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "category": "Technical Support",
    "subject": "SO-100 pairing question",
    "message": "My arm shows as offline after pairing."
  }'
Response
{
  "success": true,
  "message": "Message sent successfully",
  "id": "b1f2c3d4-0000-0000-0000-000000000000",
  "stored": true,
  "delivered": true
}
POST/api/robot-request

يطلب دعماً لنوع روبوت غير موجود بعد على المنصة.

GET/api/stats

يعيد إحصاءات عامة عن المنصة.

صفحات ذات صلة
الأمان

كيف تؤمّن AY-Robots الحسابات والتحكم المباشر بالروبوتات: مصادقة Supabase، نموذج الأدوار، مفاتيح API، ضمانات الجلسة، سجل التدقيق، والتشفير.

الجلسات

كيف تعمل جلسات AY-Robots: دورة الحياة من PENDING إلى COMPLETED، شرح كل حدث نشاط، دردشة الجلسة، التقييمات، التمديدات، وبيانات التدريب.

السابق
الروبوتات المدعومة
التالي
الفوترة والمدفوعات