المطورون / Tools
عرض قائمة الأدوات
https://api.echonova.ai/v1/toolsتعرض الأدوات في مساحة عمل هذا المفتاح، وتُقسَّم الصفحات بـ `offset` و`limit`. تعرض الأدوات عناوين URL الخاصة بها ومعرّفات الأسرار وروابط المصادقة التي تستخدمها، ولا تعرض قيم الأسرار أبدًا. استخدام هذه النقطة مجاني. يحتاج المفتاح إلى النطاق `tools:write`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
معاملات الاستعلام
عدد العناصر التي تُتخطّى.
عدد العناصر التي تُعاد.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
العناصر في هذه الصفحة.
معرّف الأداة.
اسم الأداة، ويكون فريدًا في مساحة العمل.
webhook أو openapi أو integration.
وظيفة الأداة، أو `null`.
وقت إنشاء الأداة.
وقت آخر تغيير على الأداة.
يُعبأ لأدوات webhook. لا تُعاد القيم الثابتة أبدًا.
عنوان URL الذي تستدعيه الأداة.
طريقة HTTP للاستدعاء.
أقصى مدة للاستدعاء بالمللي ثانية، أو `null` للقيمة الافتراضية.
معرّف ربط المصادقة المستخدم في الاستدعاء، أو `null`.
القيم التي يرسلها الاستدعاء.
مكان المعامل في الطلب.
مفتاح المعامل، أو اسم العنصر النائب في المسار.
نوع القيمة التي يأخذها المعامل.
هل يحتاج الاستدعاء إلى هذا المعامل.
يوضح للنموذج ما يضعه هنا، أو `null`.
llm أو constant أو secret. لا تُعاد القيم الثابتة أبدًا.
معرّف السر في الخزنة عندما يكون valueType هو secret، وإلا فهو `null`.
يُعبأ لأدوات OpenAPI.
عنوان مستند OpenAPI المستورد.
عدد العمليات التي استوردتها الأداة.
هل صار الاستيراد جاهزًا للوكلاء.
الخادم الذي تستدعيه الأداة، أو `null`.
أسماء العمليات المختارة للاستيراد، والقائمة الفارغة تعني الكل.
معرّف ربط المصادقة المرسل مع كل استدعاء، أو `null`.
سبب فشل الاستيراد، أو `null`.
يُعبأ لأدوات التكامل.
مزوّد التكامل.
مفتاح أداة التكامل.
العدد الإجمالي للعناصر.
قيمته 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.
متى يحدث. متن الطلب أو الاستعلام يحمل حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل.
متى يحدث. مساحة العمل التي يتبعها المفتاح ليس لديها اشتراك.
الحل. تحقّق من خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة ولا تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `tools:write`. النطاق `agents:write` لا يمنحه هذه الصلاحية.
الحل. عدّل المفتاح وأعطه النطاق `tools:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد لديه الصلاحيتان `Manage tools` و`Manage developer API` معًا. يُفحص هذا مع كل طلب.
الحل. أعطِ ذلك العضو الصلاحيتين من جديد، أو أنشئ مفتاحًا بعضو لديه الصلاحيتان.
متى يحدث. المفتاح أرسل أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية، أو أن عنوان IP واحدًا أرسل أكثر من 100 طلب إلى نقطة نهاية واحدة خلال 60 ثانية (يُحسب حد عنوان IP قبل فحص المفتاح، لذلك قد يرد الخادم دون أي مفتاح)؛ و header `Retry-After` يحمل عدد الثواني المطلوب انتظارها.
الحل. انتظر عدد الثواني المذكور في `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه API.
الحل. تحقّق من الطلب، ثم أعد المحاولة بعد لحظة قصيرة؛ وتواصل مع الدعم إذا تكرر الخطأ.
متى يحدث. انقطاع مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
متى يحدث. انتهاء مهلة مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
curl "https://api.echonova.ai/v1/tools" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"items": [
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Order lookup",
"type": "webhook",
"description": "Finds an order by its number.",
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z",
"webhook": {
"url": "https://api.example.com/orders/{orderId}",
"method": "GET",
"timeoutMs": 10000,
"connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
"parameters": [
{
"location": "header",
"name": "orderId",
"dataType": "string",
"required": true,
"description": "Finds an order by its number.",
"valueType": "llm",
"secretId": "YOUR_SECRET_ID"
}
]
},
"openapi": {
"apiTitle": "Orders API",
"operationCount": 12,
"status": "ready",
"baseUrl": "https://api.example.com",
"includeOperations": [
"getOrder"
],
"authConnectionId": "YOUR_AUTH_CONNECTION_ID",
"error": null
},
"integration": {
"provider": "slack",
"key": "add_reaction"
}
}
],
"total": 1
},
"success": true,
"statusCode": 200,
"errorMessage": null
}