مفاتيح API

الطرق وحقول الطلبات والردود.

الدليل الكامل

يضم القسم 5 طرق. افتح الطريقة لعرض شروط الوصول وحقول الطلب والرد.

الطريقة والمسار	الوصف	الوصول
`GET /api/v1/keys`	القائمة — مفاتيح API	توكن لوحة الحساب
`POST /api/v1/keys`	إنشاء مفتاح API	توكن لوحة الحساب
`DELETE /api/v1/keys/:id`	الحذف — مفاتيح API	توكن لوحة الحساب
`GET /api/v1/keys/:id`	الاسترجاع بالمعرّف — مفاتيح API	توكن لوحة الحساب
`PUT /api/v1/keys/:id`	تعديل مفتاح API	توكن لوحة الحساب

GET /api/v1/keys — القائمة — مفاتيح API

الوصول: توكن لوحة الحساب

GET/api/v1/keys

قراءة؛ يُؤخذ ID من رد سابق لك

curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

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

الحقل	النوع	مطلوب	التحقق / الوصف
`sort_by`	`string`	لا	؛ القيمة الافتراضية: created_at
`sort_order`	`string`	لا	؛ القيمة الافتراضية: desc
`search`	`string`	لا
`status`	`string`	لا
`page`	`integer`	لا	؛ القيمة الافتراضية: 1; positive; page_size/limit <=1000
`page_size`	`integer`	لا	؛ القيمة الافتراضية: 20; positive; page_size/limit <=1000
`limit`	`integer`	لا	؛ القيمة الافتراضية: 20; positive; page_size/limit <=1000

لا يلزم جسم للطلب. أرسل المعاملات المذكورة أعلاه في URL.

الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: APIKey. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

POST /api/v1/keys — إنشاء مفتاح API

الوصول: توكن لوحة الحساب

POST/api/v1/keys

حقول JSON / النموذج

الحقل	النوع	مطلوب	التحقق / الوصف
`name`	`string`	نعم	required
`custom_key`	`string`	لا	؛ قيمة مخصصة اختيارية للمفتاح؛ يمكن أن تكون null
`ip_whitelist`	`array`	لا	؛ قائمة عناوين IP المسموح بها
`ip_blacklist`	`array`	لا	؛ قائمة عناوين IP المحظورة
`quota`	`number`	لا	؛ حد إنفاق المفتاح بالدولار USD؛ يمكن أن يكون null
`expires_in_days`	`integer`	لا	؛ مدة الصلاحية بالأيام؛ يمكن أن تكون null
`rate_limit_5h`	`number`	لا	؛ يمكن أن يكون null
`rate_limit_1d`	`number`	لا	؛ يمكن أن يكون null
`rate_limit_7d`	`number`	لا	؛ يمكن أن يكون null

قالب جسم الطلب

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

يشير PLACEHOLDER إلى مدخلاتك ونوعها. استبدل القيم وأبقِ الحقول الاختيارية المطلوبة فقط؛ لا ترسل العلامات النصية بدلاً من الأرقام أوboolean أوالكائنات أوالمصفوفات.

مخطط الطلب: CreateAPIKeyRequest

الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: APIKey. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يدعم Idempotency-Key؛ وتعيد المحاولة المكررة الرد المحفوظ مع X-Idempotency-Replayed.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

DELETE /api/v1/keys/:id — الحذف — مفاتيح API

الوصول: توكن لوحة الحساب

DELETE/api/v1/keys/:id

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

الحقل	النوع	مطلوب	التحقق / الوصف
`id`	`integer`	نعم

لا يلزم جسم للطلب.

الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخطط الرد؛ القيم تمثيلية

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

GET /api/v1/keys/:id — الاسترجاع بالمعرّف — مفاتيح API

الوصول: توكن لوحة الحساب

GET/api/v1/keys/:id

قراءة؛ يُؤخذ ID من رد سابق لك

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

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

الحقل	النوع	مطلوب	التحقق / الوصف
`id`	`integer`	نعم

لا يلزم جسم للطلب. أرسل المعاملات المذكورة أعلاه في URL.

الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: APIKey. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

PUT /api/v1/keys/:id — تعديل مفتاح API

الوصول: توكن لوحة الحساب

PUT/api/v1/keys/:id

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

الحقل	النوع	مطلوب	التحقق / الوصف
`id`	`integer`	نعم

حقول JSON / النموذج

الحقل	النوع	مطلوب	التحقق / الوصف
`name`	`string`	لا
`status`	`string`	لا	omitempty,oneof=active inactive
`ip_whitelist`	`array`	لا	؛ عناوين IP المسموح بها: لا تغيّر null القائمة، وتُفرغها المصفوفة الفارغة؛ يمكن أن تكون null
`ip_blacklist`	`array`	لا	؛ عناوين IP المحظورة: لا تغيّر null القائمة، وتُفرغها المصفوفة الفارغة؛ يمكن أن تكون null
`quota`	`number`	لا	؛ حد إنفاق المفتاح بالدولار USD؛ 0 يعني دون حد؛ يمكن أن يكون null
`expires_at`	`string`	لا	؛ وقت انتهاء الصلاحية بصيغة ISO 8601؛ يمكن أن يكون null
`reset_quota`	`boolean`	لا	؛ إعادة تعيين الجزء المستخدم من حد الإنفاق؛ يمكن أن يكون null
`rate_limit_5h`	`number`	لا	؛ يمكن أن يكون null
`rate_limit_1d`	`number`	لا	؛ يمكن أن يكون null
`rate_limit_7d`	`number`	لا	؛ يمكن أن يكون null
`reset_rate_limit_usage`	`boolean`	لا	؛ إعادة تعيين الإنفاق المحتسب ضمن حدود النوافذ الزمنية؛ يمكن أن يكون null

قالب جسم الطلب

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

مخطط الطلب: UpdateAPIKeyRequest

الرد

يتضمن رد JSON الحقول code وmessage وdata. محتوى data موضح في المخططات أدناه.

مخططات بيانات الرد: APIKey. الحقول والأنواع موضحة في صفحات «مخططات البيانات».

مخطط الرد؛ القيم تمثيلية

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

ملاحظات: تقتصر جميع البيانات الشخصية والكائنات على صاحب الهوية في JWT.

ملاحظات: تغيّر العملية الحالة أو تواصل مصادقة لمرة واحدة؛ يصف المثال العقد ولا يتم تنفيذه.

ملاحظات: يحتوي الرد على key سرّي؛ لا تنشر القيم الحقيقية.

ملاحظات: ما دامت هناك طلبات غير مكتملة ذات مبالغ محجوزة على المفتاح، لا يمكن خفض حد إنفاقه أو إعادة تعيينه. أرسل فقط الحقول التي تعدّلها.

هل لديك أسئلة أخرى؟ أرسل Request ID ووصفاً للمشكلة وسنساعدك على فهمها.مراسلة الدعم