التوثيق

مرجع API

الاستعلام عن تشغيلات الأدوات

GET/v1/tool-runs

دعم موحّد لتسعير flat الثابت لكل استدعاء، وتسعير input المحسوب مسبقًا من المدخلات، وتسعير usage المبني على الاستخدام النهائي. يحدد pricing.quote_required إلزامية عرض السعر؛ ويحدد requires_usage الحاجة إلى سقف تكلفة واستخدام نهائي موثوق. لا يُستنتج أي منهما من schema_version. عند تعطيل metered_pricing، تُقيّد الاستدعاءات الجديدة التي تتطلب الاستخدام النهائي فقط؛ وتظل القواعد الثابتة/المبنية على المدخلات متاحة إن لم تحتج إلى استخدام نهائي. يجب أن يملك المفتاح الحالي صلاحية الأداة؛ وترتبط هوية التشغيل ونتائجه بالمفتاح الأصلي. يكون الدليل فارغًا عند تعطيل المفتاح الرئيسي للأدوات؛ ولا يمنح الدليل المجهول صلاحية التنفيذ. يسرد فقط التشغيلات المملوكة للمفتاح الأصلي، بترتيب صارم تنازليًا حسب created_at ثم تنازليًا حسب id؛ ويوفر id ترتيبًا ثابتًا ضمن الثانية نفسها. إن next_cursor مؤشر زوجي معتم ويجب إعادته دون تغيير؛ وتُرجع المؤشرات المشوهة 400 invalid_cursor. ترقيم الصفحات ليس لقطة زمنية. حدّث الصفحة الأولى لرؤية السجلات الجديدة التي تسبق المؤشر الحالي في الترتيب.

المصادقة والصلاحيات

استخدم مفتاح GloopAPI الحالي. تعتمد النماذج والإمكانات والصلاحيات المتاحة على دليله ووثائق نقطة النهاية.

Authorization: Bearer $GLOOP_API_KEY

آليات المصادقة: BearerAuth

الطلب

معاملات الاستعلام

  • cursorstringاختياري

    next_cursor من الاستجابة الأصلية؛ لا تنشئه بنفسك. تُرجع المؤشرات غير الصالحة 400 invalid_cursor.

  • limitintegerاختياري

    نطاق الدليل 1–100، وتُستخدم 20 عند القيم غير الصالحة؛ ونطاق قائمة التشغيلات 1–100، وتُستخدم 20 عند القيم غير الصالحة.

الاستجابات والأخطاء

HTTP 200

تم الاستعلام عن تشغيلات الأدوات بنجاح

application/json

النوع
object
الحقول المطلوبة
items
  • itemsarrayمطلوب

    مصفوفة الأدوات أو التشغيلات في الصفحة الحالية.

    الحقول الفرعية لـ items (1)
    • []objectاختياري
      الحقول الفرعية لـ [] (10)
      • idstringمطلوب

        المعرّف العام لهذا الكائن، المستخدم لمسار تفاصيله المقابل.

      • tool_idstringمطلوب

        معرّف الأداة من دليل الأدوات القابلة للتنفيذ للمفتاح الحالي.

      • versionstringمطلوب

        إصدار العقد/الإمكانات أو الأداة؛ تستخدم التشغيلات إصدار الأداة الذي يعيده الدليل.

      • statusstringمطلوب

        submitting/running/submission_unknown/succeeded/failed؛ تعني submission_unknown جهل نتيجة الإرسال، ولا يجوز تغيير Idempotency-Key لإعادته.

      • outputunknownمطلوب

        JSON تحدده output_schema للأداة؛ لا تفترض بقاء النتائج بعد انتهاء الصلاحية.

      • error_codestringاختياري

        رمز خطأ عام يمكن استخدامه في منطق التفرّع.

      • billingobjectمطلوب

        حالة الفوترة المستقلة؛ لا تستبدلها بحالة التوليد.

        الحقول الفرعية لـ billing (7)
        • review_requiredbooleanاختياري

          تتطلب أدلة الفوترة مراجعة يدوية.

        • reasonstringاختياري

          السبب العام لتعذر الإجراء أو مراجعة الحسابات.

        • usageunknownاختياري

          قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

        • breakdownunknownاختياري

          قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

        • statusstringمطلوب

          حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

        • reserved_usdstringمطلوب

          الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

        • charged_usdstringمطلوب

          مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

        فرع allOf رقم 1

        النوع: object

        المطلوب في هذا الفرع: status, reserved_usd, charged_usd

        • review_requiredbooleanاختياري

          تتطلب أدلة الفوترة مراجعة يدوية.

        • reasonstringاختياري

          السبب العام لتعذر الإجراء أو مراجعة الحسابات.

        • usageunknownاختياري

          قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

        • breakdownunknownاختياري

          قيمة JSON يحددها مخطط الأداة المختارة أو البروتوكول؛ لا تفترض حقولًا ثابتة.

        • statusstringمطلوب

          حالة الكائن الحالية؛ قيّمها بصورة منفصلة عن الفوترة ومرحلة الحفظ.

        • reserved_usdstringمطلوب

          الحد الأقصى للمبلغ المحجوز بالدولار الأمريكي كسلسلة نصية.

        • charged_usdstringمطلوب

          مبلغ الرسوم المؤكد حاليًا بالدولار الأمريكي كسلسلة نصية.

      • result_expiredbooleanمطلوب

        هل انتهت صلاحية النتيجة؛ تبقى سجلات الفوترة/منع التكرار.

      • created_atintegerمطلوب

        وقت الإنشاء بثواني Unix.

      • updated_atintegerمطلوب

        آخر تحديث بثواني Unix.

  • next_cursorstringاختياري

    مؤشر ثنائي معتم تمامًا created_at/id؛ يُمرر دون تغيير. التنسيق غير الصحيح يعيد 400 invalid_cursor، والغياب أو الفراغ يعني آخر صفحة.

HTTP 400

حقول الطلب أو معاملاته غير صالحة.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 401

Key مفقود أو غير صالح أو منتهي أو ملغى.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 403

صلاحيات IP أو الحساب أو النموذج أو الأداة غير كافية.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 404

الكائن/الإمكانية غير متاحين، أو مفتاح الميزة معطّل.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 409

تعارض في منع التكرار/عرض السعر، أو كائن غير جاهز، أو ما يزال مشارًا إليه.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 429

حد معدل الطلبات/قائمة الانتظار.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 500

فشل داخلي في المصادقة أو تخزين البيانات.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)

HTTP 503

الخدمة أو التسعير أو التخزين غير متاح.

application/json

النوع
object
الحقول المطلوبة
error
  • errorobjectمطلوب
    الحقول الفرعية لـ error (4)