عقد واحد للكازا الخاصة بك

العقد المقروء آليًا

يعيد GET /api/v1/openapi.json مستند OpenAPI 3.1 يصف بدقة ما ينفذه هذا النشر: كل مسار ومخطط ونطاق أذونات مطلوب ورد، إضافة إلى أحداث خطافات الويب. ويُولّد من فهرس العمليات الجاري تشغيله، وهو نفسه الذي ينتج أدوات MCP، فلا تنحرف REST وMCP إحداهما عن الأخرى أبدًا.

curl -s "https://<your host>/api/v1/openapi.json"

تشمل الواجهة الكازا والمسودات والمراجعات والمنشورات والتدوينات وفهرس القوالب والاستيراد ومجموعات النطاقات والتشغيل الجماعي والنطاقات وخطط DNS وإعادة توجيه البريد وإعدادات التسجيل والتواصل والمصادر الاجتماعية والتحليلات والترويج والفوترة وأعضاء الفريق وخطافات الويب. يوضح GET /workspaces/{id}/capabilities أي هذه الإمكانات فعالة أو محاكاة أو في انتظار بيانات اعتماد في مساحة عملك.

إعادة المحاولة مقصودة

• يتطلب كل تعديل ترويسة Idempotency-Key من 16 إلى 128 حرفًا. يعيد تكرار الطلب بالمفتاح والمتن نفسيهما النتيجة الأصلية مع Idempotent-Replayed: true. واستخدام المفتاح نفسه مع متن مختلف ينتج 409 idempotency_key_reused.
• تحتاج تعديلات الكازا إلى If-Match مع ETag من آخر قراءة لك. تنتج القيمة القديمة 412 revision_conflict ولا يتغير شيء.
• يستخدم النشر revision_id وexpected_digest الدقيقين اللذين قرأتهما، لتنشر ما فحصته.

العمل الطويل مهمة

يجيب النشر والتشغيل الجماعي وغيرهما من العمليات البطيئة بالرمز 202 مع مهمة. استطلع GET /workspaces/{id}/jobs/{job_id} بوتيرة لا تتجاوز ما تحدده next_poll_after_seconds، أو اشترك في خطافات الويب job.updated. القبول لا يعني الاكتمال: اقرأ state للمهمة وأعدادها وerror قبل الإبلاغ بالنجاح.

الأخطاء تفاصيل مشكلات

تستخدم الأخطاء application/problem+json مع code ثابت وtitle مترجم وrequest_id وretryable. اتخذ القرار بناءً على code، ولا تعتمد أبدًا على نص العنوان.

{
  "type": "https://<your host>/problems/insufficient_scope",
  "title": "This token does not include the permission this action needs.",
  "status": 403,
  "code": "insufficient_scope",
  "request_id": "01M5...",
  "retryable": false,
  "context": { "required_scope": "account:read" }
}

القوائم والحدود

• تقبل نقاط نهاية القوائم limit (حتى 100) وcursor من الصفحة السابقة.
• يجوز لكل رمز مساحة عمل إجراء 120 قراءة و30 كتابة في الدقيقة. عند تجاوز الحد، تحصل على 429 مع ترويسة Retry-After.
• احتفظ بحقول الرد غير المعروفة: قد تظهر حقول جديدة دون تغيير الإصدار.