المطورون / الوكلاء
عرض الوكلاء
https://api.echonova.ai/v1/agentsتعرض الوكلاء في مساحة العمل الخاصة بهذا المفتاح، مرتبةً من الأحدث تغييرًا إلى الأقدم، وتُقسَّم الصفحات بـ `offset` و`limit`. لا تظهر الوكلاء المؤرشفة إلا عند طلب `status=archived`. يحتاج المفتاح إلى النطاق `agents:read`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات الاستعلام
عدد العناصر التي تُتخطّى.
عدد العناصر التي تُعاد.
الوكلاء في هذه الحالة فقط. اتركه فارغًا لعرض كل وكيل غير مؤرشف.
الوكلاء التي يحتوي اسمها على هذا النص فقط.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
العناصر في هذه الصفحة.
معرّف الوكيل.
اسم الوكيل.
الغرض من الوكيل، أو `null`.
`active`، أو `archived` بعد حذفه من البوابة.
الصوت الافتراضي للوكيل، أو `null` إن لم يكن له صوت.
معرّف الصوت كما يعرضه `GET /v1/text-to-speech/voices`.
اسم الصوت بالإنجليزية، أو `null` إن لم يعد الصوت متاحًا.
لهجة الصوت الافتراضي، أو `null`.
نموذج اللغة الذي يفكّر به الوكيل.
الجهة التي تقدّم نموذج اللغة.
معرّف النموذج. مرّره كقيمة لـ `model` في `GET /v1/llm/estimate` لمعرفة سعره.
عدد القنوات المتصل بها الوكيل.
عدد المحادثات التي أجراها الوكيل.
وقت آخر تعديل على الوكيل، بصيغة ISO 8601 للتاريخ والوقت.
العدد الإجمالي للعناصر.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. قيمة `offset` في قائمة المهام سالبة.
الحل. أرسل 0 أو أكثر.
متى يحدث. قيمة `offset` ليست عددًا صحيحًا.
الحل. أرسل عددًا صحيحًا.
متى يحدث. قيمة `offset` في قائمة أكبر من 10000.
الحل. أرسل قيمة من 0 إلى 10000.
متى يحدث. قيمة `limit` أقل من 1.
الحل. أرسل 1 أو أكثر.
متى يحدث. قيمة `limit` في قائمة أو في النص المفرّغ أكبر من 50.
الحل. أرسل قيمة من 1 إلى 50، وتنقّل بين الصفحات بـ `offset` (أو بـ `before` للنص المفرّغ).
متى يحدث. قيمة `limit` ليست رقمًا أصلًا.
الحل. أرسل عددًا صحيحًا من 1 إلى 50.
متى يحدث. الجسم أو معلمات الاستعلام تحتوي على حقل لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. قيمة `status` أي قيمة أخرى.
الحل. أرسل `active` أو `archived`، أو اتركه فارغًا.
متى يحدث. قيمة `q` أطول من 100 حرف.
الحل. أرسل بحثًا أقصر.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. مساحة العمل المالكة للمفتاح ليس لها اشتراك.
الحل. راجع خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة أو تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `agents:read`. الوصول إلى الكلام وتذاكر أداة الموقع لا يمنحه هذا النطاق.
الحل. عدّل المفتاح وامنحه النطاق `agents:read`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد يملك صلاحيتي عرض الوكلاء وإدارة واجهة المطورين معًا. يُفحص ذلك في كل طلب.
الحل. امنح ذلك العضو الصلاحيتين من جديد، أو أنشئ المفتاح بعضو يملكهما.
متى يحدث. أرسل المفتاح أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أرسل عنوان IP واحد أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يردّ بلا مفتاح أصلًا)؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه الواجهة.
الحل. راجع الطلب، ثم أعد المحاولة بعد انتظار قصير، وتواصل مع الدعم إن استمر الخطأ.
متى يحدث. انقطاع مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
متى يحدث. انتهاء مهلة مؤقت داخل الواجهة.
الحل. أعد المحاولة بعد انتظار قصير.
curl "https://api.echonova.ai/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"items": [
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Sales assistant",
"description": "Answers questions about plans and prices.",
"status": "active",
"voice": {
"id": "6640a1b2c3d4e5f6a7b8c9d0",
"name": "Huda"
},
"dialect": "emirati",
"llm": {
"provider": "openai",
"model": "gpt-4o"
},
"channelsCount": 2,
"sessionsCount": 128,
"updatedAt": "2026-11-01T10:00:00.000Z"
}
],
"total": 1
},
"success": true,
"statusCode": 200,
"errorMessage": null
}