GET/v1/permissions
عرض سجل الصلاحيات
list_permissions
يعيد كل صفوف الصلاحيات حسب المستوى (ORG، COLLECTION، CARD، SOURCE، AGENT) مع أسمائها وأوصافها بلغتين. متاحة لأي مستخدم مسجّل الدخول.
المصادقة
أرسل مفتاح API في الترويسة Authorization: Authorization: Bearer <key>.
معاملات الاستعلام
limitintegerحجم الصفحة. دون المعاملين
limitوcursorتُعاد القائمة كاملة؛ ومع المعامل تُعاد عناصر بعددlimitعلى الأكثر، وتُعطى الصفحة التالية في الترويستينLink(rel="next") وX-Next-Cursor.≥ 1, ≤ 200
cursorstringمؤشر الصفحة التالية من الترويسة
X-Next-Cursorأو من الحقلnext_cursorفي الاستجابة السابقة بعوامل التصفية نفسها؛ ويحمل حجم الصفحة. مع المعاملoffsetمعًا:422 validation.failed؛ ومؤشر قائمة أخرى أو عوامل تصفية أخرى أو مؤشر تالف:400 api.cursor_invalid.length ≤ 512
الاستجابات
200استجابة ناجحة
ترويسات الاستجابة
Linkعنوان الصفحة التالية،
<…>; rel="next". غياب الترويسة يعني أن هذه الصفحة الأخيرة.X-Next-Cursorمؤشر الصفحة التالية للمعامل
cursor. غياب الترويسة يعني أن هذه الصفحة الأخيرة.RateLimit-Policyالحدود السارية، بصيغة مسودة IETF
draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل"<name>";q=<quota>;w=<window in seconds>. العنصرkeyهو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكونuser، ودون بيانات اعتمادip)؛ وminuteوdayوmonthهي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.RateLimitالمتبقي من كل حد في الترويسة
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-Limitحد العنصر الأشد صرامة في الترويسة
RateLimit-Policy(العنصر الذي بقي فيه أقل عدد من الطلبات).X-RateLimit-Remainingعدد الطلبات المتبقية ضمن الحد الأشد صرامة.
X-RateLimit-Resetعدد الثواني حتى إعادة ضبط الحد الأشد صرامة.
application/json
keystringمطلوبtitlestringمطلوبdescriptionstringمطلوبsortintegerمطلوب
401لم تُرسَل بيانات اعتماد (لا ملف تعريف ارتباط للجلسة ولا مفتاح API)، أو لم يُعثر على المفتاح.
ترويسات الاستجابة
RateLimit-Policyالحدود السارية، بصيغة مسودة IETF
draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل"<name>";q=<quota>;w=<window in seconds>. العنصرkeyهو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكونuser، ودون بيانات اعتمادip)؛ وminuteوdayوmonthهي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.RateLimitالمتبقي من كل حد في الترويسة
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-Limitحد العنصر الأشد صرامة في الترويسة
RateLimit-Policy(العنصر الذي بقي فيه أقل عدد من الطلبات).X-RateLimit-Remainingعدد الطلبات المتبقية ضمن الحد الأشد صرامة.
X-RateLimit-Resetعدد الثواني حتى إعادة ضبط الحد الأشد صرامة.
application/json
429طلبات كثيرة جدًا (`api.rate_limited`)، أو استُنفدت حصة المؤسسة للدقيقة أو اليوم أو الشهر (`api.quota_exceeded`؛ يحتوي الحقل `error.details` على `quota` و`limit` و`reset_at`)، أو بلغت المؤسسة حدها، أو خدمة الإجابات مشغولة (`answers.engine_busy`). انتظر المدة المذكورة في الترويسة `Retry-After`.
ترويسات الاستجابة
Retry-Afterعدد الثواني التي تنتظرها قبل إعادة محاولة الطلب.
RateLimit-Policyالحدود السارية، بصيغة مسودة IETF
draft-ietf-httpapi-ratelimit-headers: عناصر مفصولة بفواصل"<name>";q=<quota>;w=<window in seconds>. العنصرkeyهو معدل طلبات مفتاح API (الحصة هي هامش الذروة، والنافذة الزمنية هي مدة إعادة ملئه بالكامل؛ وللجلسة يكونuser، ودون بيانات اعتمادip)؛ وminuteوdayوmonthهي حصص المؤسسة للدقيقة واليوم والشهر التقويمية بتوقيت UTC.RateLimitالمتبقي من كل حد في الترويسة
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-Limitحد العنصر الأشد صرامة في الترويسة
RateLimit-Policy(العنصر الذي بقي فيه أقل عدد من الطلبات).X-RateLimit-Remainingعدد الطلبات المتبقية ضمن الحد الأشد صرامة.
X-RateLimit-Resetعدد الثواني حتى إعادة ضبط الحد الأشد صرامة.
application/json
رموز الأخطاء
الرموز التي قد تعيدها نقطة النهاية هذه في error.code، إضافةً إلى الرموز العامة لكل طلب.
حدود المعدل
تحمل الاستجابات الترويستين RateLimit وRateLimit-Policy، والترويسات الأقدم X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. وفي الاستجابة 429 الترويسة Retry-After بالثواني: انتظر ثم أعد المحاولة.