الواجهة البرمجية العامة

تتيح الواجهة البرمجية العامة لخوادمك استدعاء وكلائك. وهي منفصلة عن لوحة التحكم: لها مفاتيحها ووثائقها وحدودها الخاصة.

• العنوان الأساسي: https://api.backcrew.ai/v1
• المرجع التفاعلي: https://api.backcrew.ai/v1/docs

المصادقة

أنشئ مفتاحًا سريًا من الإعدادات ثم مفاتيح API. يبدأ المفتاح بـ bk_live_ ولا يُعرض إلا مرة واحدة، فاحفظه في مكان آمن. أرسله مع كل طلب:

Authorization: Bearer bk_live_...

أبقِه على خادمك

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

عرض وكلائك

curl https://api.backcrew.ai/v1/agents \
  -H "Authorization: Bearer $BACKCREW_API_KEY"

[{ "id": "7c9f…", "name": "support-bot", "status": "deployed" }]

لا يجيب إلا الوكلاء بحالة deployed.

إرسال رسالة

POST /v1/agents/{agent_id}/invoke

الحقل	مطلوب	المعنى
prompt	نعم	الرسالة.
session_id	لا	يجمع الرسائل في محادثة واحدة.
user_id	لا	معرّفك الخاص للشخص الذي تتصرف نيابةً عنه. عند تفعيل الذاكرة، يحصل كل user_id على ذاكرته الخاصة.

curl -X POST https://api.backcrew.ai/v1/agents/$AGENT_ID/invoke \
  -H "Authorization: Bearer $BACKCREW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "أين طلبي؟", "user_id": "customer-123", "session_id": "conversation-1"}'

{
  "response": "تم شحن طلبك أمس ومن المتوقع وصوله يوم الخميس.",
  "usage": { "input_tokens": 1240, "output_tokens": 310, "credits_charged": 5, "unmetered": [] }
}

يصل الرد كاملًا عند انتهاء الوكيل، فالردود لا تُبث تدريجيًا.

Python

import os, requests

res = requests.post(
    f"https://api.backcrew.ai/v1/agents/{os.environ['AGENT_ID']}/invoke",
    headers={"Authorization": f"Bearer {os.environ['BACKCREW_API_KEY']}"},
    json={"prompt": "أين طلبي؟", "user_id": "customer-123"},
    timeout=320,
)
res.raise_for_status()
print(res.json()["response"])

JavaScript

const res = await fetch(`https://api.backcrew.ai/v1/agents/${agentId}/invoke`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BACKCREW_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "أين طلبي؟", user_id: "customer-123" }),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
console.log((await res.json()).response);

الأخطاء

الرمز	المعنى
401	المفتاح مفقود أو غير معروف أو ملغى.
402	نفدت أرصدة مساحة العمل (أو تجاوزت حدها الشهري).
404	لا يوجد وكيل بهذا المعرّف في مساحة عمل هذا المفتاح.
409	الوكيل غير منشور حاليًا (مثلًا: قيد التحديث).
429	بلغت حد المعدل؛ انتظر عدد الثواني في Retry-After.
502	تعذّر على الوكيل الإجابة.
504	تجاوز الوكيل الحد الأقصى لمدة الطلب (5 دقائق).

الحدود والتكلفة

• 60 طلبًا في الدقيقة لكل مفتاح.
• يستهلك كل استدعاء أرصدة تمامًا كطلب من لوحة التحكم. راجع الأرصدة.