מפתחות 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

קריאה; המזהה נלקח מהתשובה הקודמת שקיבלתם

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

פרמטרי Query

השדה	טיפוס	חובה	בדיקה / תיאור
`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)"
  }
}

מאפיינים: כל הנתונים האישיים והאובייקטים מוגבלים לזהות ה-subject ב-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)"
  }
}

מאפיינים: כל הנתונים האישיים והאובייקטים מוגבלים לזהות ה-subject ב-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"
  }
}

מאפיינים: כל הנתונים האישיים והאובייקטים מוגבלים לזהות ה-subject ב-JWT.

מאפיינים: הפעולה משנה מצב או ממשיכה תהליך אימות חד-פעמי; הדוגמה מתארת את החוזה ואינה מבוצעת.

מאפיינים: התשובה מכילה key סודי; אין לפרסם ערכים אמיתיים.

GET /api/v1/keys/:id — קבלה לפי מזהה — מפתחות API

גישה: טוקן של האזור האישי

GET/api/v1/keys/: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)"
  }
}

מאפיינים: כל הנתונים האישיים והאובייקטים מוגבלים לזהות ה-subject ב-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)"
  }
}

מאפיינים: כל הנתונים האישיים והאובייקטים מוגבלים לזהות ה-subject ב-JWT.

מאפיינים: הפעולה משנה מצב או ממשיכה תהליך אימות חד-פעמי; הדוגמה מתארת את החוזה ואינה מבוצעת.

מאפיינים: התשובה מכילה key סודי; אין לפרסם ערכים אמיתיים.

מאפיינים: כל עוד יש במפתח בקשות שלא הושלמו ושנשמרה עבורן רזרבה, אי אפשר להקטין או לאפס את מגבלת ההוצאות שלו. העבירו רק את השדות שאתם משנים.

נשארו שאלות? שלחו Request ID ותיאור — נעזור לברר.פנייה לתמיכה