واجهة برمجة تطبيقات حاسوب الوكيل

جربها في ملعب واجهة برمجة التطبيقات (API Playground).

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

https://api.rebyte.ai/v1

المصادقة

يتطلب كل طلب رأس API_KEY. احصل على مفتاحك من الإعدادات > مفاتيح API.

curl https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_your_key_here"

اسم الرأس غير حساس لحالة الأحرف. تعمل كل من API_KEY وapi-key وx-api-key.

---

نقاط النهاية

الطريقة	المسار	الوصف
POST	/tasks	إنشاء مهمة
GET	/tasks	سرد المهام
GET	/tasks/:id	الحصول على مهمة مع الحالة وسجل المطالبات
POST	/tasks/:id/prompts	إرسال مطالبة متابعة
PATCH	/tasks/:id/visibility	تغيير رؤية المهمة
DELETE	/tasks/:id	حذف مهمة بشكل ناعم
GET	/tasks/:id/events	تدفق SSE لأحداث التنفيذ
POST	/files	الحصول على عنوان URL موقع لرفع الملفات
POST	/webhooks	تسجيل webhook
GET	/webhooks	سرد الـ webhooks
GET	/webhooks/:id	الحصول على تفاصيل webhook
DELETE	/webhooks/:id	حذف webhook
جميع المسارات نسبية لعنوان URL الأساسي (https://api.rebyte.ai/v1).

---

المهام

إنشاء مهمة

POST /tasks

ينشئ مهمة جديدة. بشكل افتراضي، يوفر جهازًا افتراضيًا جديدًا (حاسوب وكيل). مرر workspaceId لتشغيل المهمة على مساحة عمل موجودة بدلاً من ذلك — هذا يتخطى عملية التوفير ويكون أسرع بكثير.

تتوقف المكالمة حتى يتم توفير الجهاز الافتراضي وتقديم المطالبة الأولى.

جسم الطلب:

الحقل	النوع	مطلوب	الوصف
prompt	string	نعم	وصف المهمة (100,000 حرف كحد أقصى)
executor	string	لا	claude (افتراضي)، gemini، codex، opencode
model	string	لا	مستوى النموذج للمنفذ. انظر النماذج.
workspaceId	string	لا	UUID لمساحة عمل موجودة لإعادة استخدامها
files	object[]	لا	الملفات من POST /files. كل منها: {"id": "...", "filename": "..."}
skills	string[]	لا	معرفات المهارات (مثل: ["deep-research", "pdf"])
githubUrl	string	لا	مستودع GitHub بتنسيق owner/repo
branchName	string	لا	اسم الفرع (افتراضي: main)

curl -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a REST API with Express and add tests",
    "executor": "claude",
    "skills": ["deep-research"],
    "githubUrl": "your-org/your-repo"
  }'

الاستجابة (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspaceId": "660e8400-e29b-41d4-a716-446655440001",
  "url": "https://app.rebyte.ai/run/550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "createdAt": "2026-01-28T12:00:00.000Z"
}

احفظ workspaceId من الاستجابة لإنشاء مهام متابعة على نفس حاسوب الوكيل:

# المهمة الأولى -- توفير جهاز افتراضي جديد
RESP=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d '{"prompt": "Set up the project"}')
WS_ID=$(echo $RESP | jq -r '.workspaceId')

# المهمة الثانية -- إعادة استخدام نفس الجهاز الافتراضي (أسرع بكثير)
curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" -H "Content-Type: application/json" \
  -d "{\"prompt\": \"Now add tests\", \"workspaceId\": \"$WS_ID\"}"

النماذج

تعتمد النماذج المتاحة على المنفذ:

المنفذ	النماذج المتاحة	الافتراضي
claude	claude-sonnet-4.6, claude-opus-4.6, gemini-3.1-pro, gpt-5.3-codex, gpt-5.4, minimax-m2.7, kimi-k2.5, glm-5, gemini-3-flash	claude-sonnet-4.6
codex	gpt-5.4, gpt-5.3-codex	gpt-5.4
gemini	auto-gemini-3 (توجيه تلقائي بين flash و pro)	auto-gemini-3
opencode	نفس claude	gemini-3.1-pro

مع BYOK (أحضر مفتاح API الخاص بك)، تتوفر فقط نماذج المزود الأصلي للمنفذ (على سبيل المثال، منفذ claude مع BYOK يحصل فقط على claude-sonnet-4.6 وclaude-opus-4.6).

سرد المهام

GET /tasks?limit=50&offset=0

يعيد المهام التي تم إنشاؤها عبر واجهة برمجة التطبيقات، مرتبة حسب وقت الإنشاء (الأحدث أولاً).

المعلمة	النوع	الافتراضي	الوصف
limit	number	50	النتائج لكل صفحة (100 كحد أقصى)
offset	number	0	إزاحة ترقيم الصفحات

curl "https://api.rebyte.ai/v1/tasks?limit=10" \
  -H "API_KEY: rbk_xxx"

الاستجابة:

{
  "data": [
    {
      "id": "550e8400-...",
      "url": "https://app.rebyte.ai/run/550e8400-...",
      "title": "Build REST API with Express",
      "executor": "claude",
      "model": "claude-sonnet-4.6",
      "createdAt": "2026-01-28T12:00:00.000000+00:00",
      "completedAt": "2026-01-28T12:05:00.000000+00:00"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

الحصول على مهمة

GET /tasks/:id

يعيد تفاصيل المهمة الكاملة بما في ذلك سجل المطالبات والحالة المشتقة.

curl https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

الاستجابة:

{
  "id": "550e8400-...",
  "url": "https://app.rebyte.ai/run/550e8400-...",
  "status": "running",
  "title": "Build REST API with Express",
  "executor": "claude",
  "model": "claude-sonnet-4.6",
  "createdAt": "2026-01-28T12:00:00.000000+00:00",
  "completedAt": null,
  "prompts": [
    {
      "id": "660e8400-...",
      "status": "running",
      "submittedAt": "2026-01-28T12:05:00.000000+00:00",
      "completedAt": null
    },
    {
      "id": "550e8400-...",
      "status": "succeeded",
      "submittedAt": "2026-01-28T12:00:01.000000+00:00",
      "completedAt": "2026-01-28T12:03:00.000000+00:00"
    }
  ]
}

حالة المهمة مشتقة من حالات المطالبات:

الحالة	الشرط
running	أي مطالبة تكون pending أو running
completed	جميع المطالبات نهائية، الأحدث هي succeeded
failed	جميع المطالبات نهائية، الأحدث هي failed
canceled	جميع المطالبات نهائية، الأحدث هي canceled

إرسال متابعة

POST /tasks/:id/prompts

أرسل مطالبة متابعة إلى مهمة قيد التشغيل أو مكتملة. إذا تم إيقاف الجهاز الافتراضي، فإنه يستأنف تلقائيًا.

الحقل	النوع	مطلوب	الوصف
prompt	string	نعم	مطالبة المتابعة (100,000 حرف كحد أقصى)
skills	string[]	لا	معرفات المهارات الإضافية لهذه المطالبة

curl -X POST https://api.rebyte.ai/v1/tasks/550e8400-.../prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add authentication with JWT"}'

الاستجابة (201):

{
  "promptId": "770f9500-..."
}

بث الأحداث (SSE)

GET /tasks/:id/events

يفتح تدفق أحداث مرسلة من الخادم (Server-Sent Events) لأحدث مطالبة للمهمة. تتضمن الأحداث مخرجات الوكيل (stdout, stderr)، استدعاءات الأدوات، وإشارات الإكمال.

curl -N https://api.rebyte.ai/v1/tasks/550e8400-.../events \
  -H "API_KEY: rbk_xxx"

يبث التدفق نوعين من الأحداث:

• event — أحداث التنفيذ (مخرجات الوكيل، استدعاءات الأدوات)
• done — الحدث النهائي مع حالة الإكمال، ثم يغلق التدفق

تغيير الرؤية

PATCH /tasks/:id/visibility

الحقل	النوع	مطلوب	الوصف
visibility	string	نعم	private، shared، أو public

المستوى	من يمكنه العرض
private	مالك مفتاح API فقط
shared	جميع أعضاء المنظمة (افتراضي)
public	أي شخص لديه الرابط (للقراءة فقط)

curl -X PATCH https://api.rebyte.ai/v1/tasks/550e8400-.../visibility \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"visibility": "public"}'

عند التعيين على public، تتضمن الاستجابة shareUrl للوصول غير المصادق عليه.

حذف مهمة

DELETE /tasks/:id

يحذف المهمة بشكل ناعم. يعيد 204 No Content.

curl -X DELETE https://api.rebyte.ai/v1/tasks/550e8400-... \
  -H "API_KEY: rbk_xxx"

---

الملفات

رفع الملفات لإرفاقها بالمهام. يستخدم تدفق URL موقع من خطوتين.

الخطوة 1: الحصول على عنوان URL للرفع

POST /files

الحقل	النوع	مطلوب	الوصف
filename	string	نعم	اسم الملف (255 حرف كحد أقصى)
contentType	string	لا	نوع MIME (افتراضي: application/octet-stream)

الاستجابة (201):

{
  "id": "550e8400-...",
  "filename": "data.csv",
  "uploadUrl": "https://storage.googleapis.com/...",
  "maxFileSize": 52428800
}

ينتهي صلاحية عنوان URL للرفع في ساعة واحدة.

الخطوة 2: رفع الملف

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv

الخطوة 3: إرفاق بالمهمة

مرر id وfilename من الخطوة 1 عند إنشاء مهمة:

{
  "prompt": "Analyze the uploaded data",
  "files": [
    {"id": "550e8400-...", "filename": "data.csv"}
  ]
}

يتم نسخ الملفات تلقائيًا إلى الجهاز الافتراضي للمهمة عند بدء التنفيذ.

---

الـ Webhooks

تلقي إشعارات HTTP POST عند حدوث أحداث المهمة. الـ Webhooks عالمية — يتم تشغيلها لجميع المهام في مؤسستك، سواء تم إنشاؤها عبر API أو واجهة المستخدم أو أي قناة أخرى.

الأحداث

الحدث	يتم تشغيله عندما
task.created	يتم إنشاء مهمة جديدة
task.running	يبدأ الوكيل في التنفيذ
task.completed	تكتمل المهمة بنجاح
task.failed	تفشل المهمة
task.canceled	يتم إلغاء المهمة من قبل المستخدم

إنشاء Webhook

POST /webhooks

الحقل	النوع	مطلوب	الوصف
url	string	نعم	عنوان URL لنقطة نهاية HTTPS
events	string[]	نعم	الأحداث للاشتراك فيها
description	string	لا	تسمية قابلة للقراءة البشرية (500 حرف كحد أقصى)
secret	string	لا	سر مشترك مسبقًا (500 حرف كحد أقصى). عند التعيين، يتم تضمينه كرأس X-Webhook-Secret في كل تسليم.

# Webhook بدون سر
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"]
  }'

# Webhook بسر مشترك مسبقًا
curl -X POST https://api.rebyte.ai/v1/webhooks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["task.completed", "task.failed"],
    "secret": "my-shared-secret-value"
  }'

الاستجابة (201):

{
  "id": "880e8400-...",
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "task.failed"],
  "description": null,
  "hasSecret": true,
  "isActive": true,
  "createdAt": "2026-01-28T12:00:00.000Z",
  "lastTriggeredAt": null,
  "failureCount": 0
}

ملاحظات السلوك:

• عناوين URL المكررة: تسجيل نفس عنوان URL مرتين يعيد الـ webhook الموجود (متطابق)
• الحد الأقصى: 3 webhooks كحد أقصى لكل مؤسسة. الرابع يعيد limit_exceeded.
• تخزين السر: لا يتم إرجاع قيمة السر أبدًا في أي استجابة. يتم الكشف عن hasSecret: true/false فقط.

سرد الـ Webhooks

GET /webhooks

يعيد جميع الـ webhooks لمؤسستك مع معلومات الحالة (lastTriggeredAt، failureCount، isActive). لا يتم الكشف عن الأسرار أبدًا.

الحصول على Webhook

GET /webhooks/:id

حذف Webhook

DELETE /webhooks/:id

يعيد 204 No Content. تتوقف الـ webhooks المحذوفة فورًا عن تلقي التسليمات.

التسليم

عندما يتطابق حدث مهمة مع الأحداث المشترك فيها لـ webhook، يرسل Rebyte طلب HTTP POST إلى عنوان URL الخاص بالـ webhook.

الحمولة:

{
  "event": "task.completed",
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1706443200,
  "data": {
    "status": "succeeded",
    "taskUrl": "https://app.rebyte.ai/run/550e8400-...",
    "result": "Created CSV file with 10 Hacker News posts..."
  }
}

• status — حالة المطالبة: pending (task.created)، running (task.running)، succeeded (task.completed)، failed (task.failed)، canceled (task.canceled)
• taskUrl — رابط مباشر للمهمة في واجهة مستخدم Rebyte (موجود دائمًا)
• result — نص الإخراج النهائي للذكاء الاصطناعي (موجود في الأحداث النهائية: task.completed، task.failed، task.canceled؛ غائب في task.created وtask.running)

استدعِ GET /tasks/:id للحصول على تفاصيل المهمة الكاملة بما في ذلك سجل المطالبات.

رؤوس التسليم:

الرأس	موجود دائمًا	الوصف
Content-Type	نعم	application/json
X-Webhook-Signature	نعم	توقيع RSA-SHA256 مشفر بـ Base64
X-Webhook-Timestamp	نعم	طابع زمني Unix (بالثواني)
X-Webhook-Secret	فقط إذا تم تكوين السر	قيمة السر المشترك مسبقًا التي قمت بتعيينها عند الإنشاء

مهلة: تنتهي مهلة التسليمات بعد 10 ثوانٍ.

معالجة الفشل:

• التسليم هو إرسال ونسيان — لا توجد إعادة محاولة تلقائية عند الفشل
• الاستجابات غير 2xx تزيد failureCount
• بعد 10 إخفاقات متتالية، يتم تعطيل الـ webhook تلقائيًا (isActive: false)
• التسليمات الناجحة تعيد تعيين failureCount إلى 0

التحقق من التوقيع

يتم توقيع كل تسليم بزوج مفاتيح RSA-2048 الخاص بمؤسستك، بغض النظر عما إذا كان قد تم تكوين سر مشترك مسبقًا.

كيف يعمل:

1. يقوم Rebyte بدمج {timestamp}.{body} (على سبيل المثال، 1706443200.{"event":"task.completed",...})
2. يوقع السلسلة باستخدام RSA-SHA256 باستخدام المفتاح الخاص لمؤسستك
3. يرسل التوقيع المشفر بـ base64 في X-Webhook-Signature

احصل على مفتاحك العام: اتصل بالدعم أو استرجعه من لوحة تحكم Rebyte. يتم إنشاء زوج مفاتيح RSA-2048 تلقائيًا عند إنشاء أول webhook ويستمر للمؤسسة.

مثال التحقق (Node.js):

const crypto = require('crypto');

function verifyWebhook(rawBody, timestamp, signature, publicKey) {
  const payload = `${timestamp}.${rawBody}`;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(payload);
  return verifier.verify(publicKey, signature, 'base64');
}

// في معالج الـ webhook الخاص بك:
app.post('/webhook', (req, res) => {
  const rawBody = req.body; // يجب أن تكون سلسلة نصية خام، وليست JSON محللة
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhook(rawBody, timestamp, signature, PUBLIC_KEY)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  console.log(`Task ${event.taskId}: ${event.event}`);
  res.status(200).send('OK');
});

مثال التحقق (Python):

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def verify_webhook(raw_body: str, timestamp: str, signature: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    payload = f"{timestamp}.{raw_body}".encode()
    try:
        public_key.verify(
            base64.b64decode(signature),
            payload,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception:
        return False

أمان ذو طبقتين

تدعم الـ Webhooks طريقتين مستقلتين للتحقق يمكن استخدامهما معًا:

الطريقة	الرأس	كيف يعمل	حالة الاستخدام
توقيع RSA	X-Webhook-Signature	إثبات تشفيري بأن الحمولة جاءت من Rebyte	تحقق مقاوم للتلاعب
سر مشترك مسبقًا	X-Webhook-Secret	سلسلة نصية ثابتة تحددها عند الإنشاء، يتم إرجاعها في كل تسليم	فحص بسيط للسر المشترك

توقيعات RSA موجودة دائمًا. السر المشترك مسبقًا اختياري — قم بتعيينه عند إنشاء الـ webhook إذا كنت تريد مسار تحقق أبسط.

---

مثال الاستقصاء (Polling)

مثال كامل: إنشاء مهمة، استقصاء حتى الاكتمال، ثم إرسال متابعة.

# إنشاء مهمة
TASK_ID=$(curl -s -X POST https://api.rebyte.ai/v1/tasks \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a Python CLI that converts CSV to JSON"}' | jq -r '.id')

echo "Task: https://app.rebyte.ai/run/$TASK_ID"

# استقصاء حتى الانتهاء
while true; do
  STATUS=$(curl -s https://api.rebyte.ai/v1/tasks/$TASK_ID \
    -H "API_KEY: rbk_xxx" | jq -r '.status')
  echo "Status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 5
done

# إرسال متابعة
curl -s -X POST https://api.rebyte.ai/v1/tasks/$TASK_ID/prompts \
  -H "API_KEY: rbk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Now add support for nested JSON objects"}'

---

تنسيق الخطأ

تتبع جميع الأخطاء هذا الهيكل:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body"
  }
}

الرمز	حالة HTTP	الوصف
missing_api_key	401	لم يتم توفير رأس API_KEY
invalid_api_key	401	مفتاح API غير صالح أو منتهي الصلاحية
validation_error	400	فشل جسم الطلب في التحقق
not_found	404	المورد غير موجود أو غير قابل للوصول
limit_exceeded	400	تم الوصول إلى حد المؤسسة (على سبيل المثال، الحد الأقصى للـ webhooks)
agent_disabled	403	المنفذ المطلوب معطل لهذه المؤسسة
internal_error	500	فشل من جانب الخادم

تحديد المعدل

لا تفرض واجهة برمجة التطبيقات حاليًا حدودًا للمعدل لكل مفتاح. كل POST /tasks يوفر جهازًا افتراضيًا حقيقيًا، لذا تتناسب التكاليف مع الاستخدام. استخدم الـ webhooks بدلاً من الاستقصاء المكثف لتقليل الطلبات غير الضرورية.