المطورون / Tools

إنشاء أداة OpenAPI

POST https://api.echonova.ai/v1/tools/openapi

يستورد مستند OpenAPI، مضمَّنًا أو من عنوان URL عام، كأداة واحدة فيها عملية لكل نقطة نهاية. تُربط اتصالات المصادقة وترويسات الأسرار بمعرّفاتها، وتُرفض القيم النصية العادية التي تبدو كبيانات اعتماد. تُفهرس عملية الاستيراد قبل أن يردّ الطلب. أرسل `Idempotency-Key` لإعادة المحاولة بأمان. الحد الأقصى 5 استدعاءات في الدقيقة لكل مفتاح. تُربط الأسرار بمعرّفاتها من GET /v1/secrets، ولا تُدخل قيمها إلا في خزنة البوابة. الخدمة مجانية. يحتاج المفتاح إلى النطاق `tools:write`.

Headers

Authorization string مطلوب

كلمة ⁦Bearer⁩ ثم مسافة ثم مفتاح ⁦API⁩ الذي يبدأ بـ ⁦ek_⁩. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.

Idempotency-Key string اختياري

اختياري. كرّر المفتاح نفسه خلال 24 ساعة لإعادة المحاولة بأمان: تعود النتيجة الأولى، ولا يُنشأ شيء مرتين. الطلب الجديد يحتاج إلى مفتاح جديد.

متن الطلب

application/json

spec object اختياري

مستند OpenAPI بصيغة JSON، بحجم يصل إلى 5 ميغابايت. أرسل واحدًا فقط من `spec` أو `url`.

url string اختياري

عنوان URL عام بروتوكول https لمستند OpenAPI. أرسل واحدًا فقط من `spec` أو `url`.

حتى 2000 حرفًا
name string مطلوب

اسم الأداة، ويجب أن يكون فريدًا في مساحة العمل.

من 1 إلى 120 حرفًا
description string اختياري

الغرض من واجهة البرمجة.

حتى 500 حرفًا
baseUrlOverride string مطلوب

الخادم الذي تستدعيه الأداة.

حتى 2000 حرفًا
includeOperations array of string اختياري

أسماء العمليات المراد استيرادها. اتركه فارغًا لاستيراد الكل.

authConnectionId string اختياري

معرّف اتصال المصادقة المرسَل مع كل استدعاء. اعرض المعرّفات عبر GET /v1/auth-connections. اتركه فارغًا لواجهة عامة لا تحتاج مصادقة.

operationEdits array of objects اختياري

وصف كل عملية، والقيم الثابتة لها، ومصادقتها.

الاستجابة

200 application/json كل استجابة تستخدم هذا الغلاف.

data object

النتيجة.

success boolean

قيمته ⁦true⁩ عند نجاح الطلب.

statusCode integer

يكرر رمز حالة ⁦HTTP⁩.

errorMessage string or null

قيمته ⁦null⁩ عند النجاح.

الأخطاء

الغلاف نفسه، مع ⁦success⁩ بقيمة ⁦false⁩ و ⁦data⁩ بقيمة ⁦null⁩. كل الأخطاء

POST /v1/tools/openapi

curl -X POST "https://api.echonova.ai/v1/tools/openapi" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Orders API","baseUrlOverride":"https://api.example.com"}'

{
  "data": {
    "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"
    }
  },
  "success": true,
  "statusCode": 200,
  "errorMessage": null
}