// api

مرجع API

مستندات REST API برای توسعه‌دهندگان

AI Score شاخص اصلی کیفیت است

AI Score (۰-۱۰۰) شاخص اصلی کیفیت مهارت‌هاست و توسط بازبینی خودکار محتوای SKILL.md تولید می‌شود. سیستم امتیازدهی کاربری از UI حذف شده، اما اندپوینت‌های /api/ratings برای سازگاری حفظ شده‌اند و اکنون منسوخ هستند. در پاسخ /api/skills فیلدهای rating/ratingCount معمولاً null هستند. به فیلد aiScore تکیه کنید.

آدرس پایه

https://skills.palebluedot.live

احراز هویت

اکثر endpointها عمومی هستند و نیازی به احراز هویت ندارند. endpointهایی که داده کاربر را تغییر می‌دهند نیاز به احراز هویت GitHub OAuth دارند.

برای ایجاد نشست در skills.palebluedot.live وارد شوید. endpointهای احراز هویت‌شده در صورت نبود نشست معتبر خطای 401 برمی‌گردانند.

محدودیت نرخ

تمام endpointها با الگوریتم پنجره لغزان محدود شده‌اند. هدرهای محدودیت نرخ در پاسخ‌ها درج می‌شوند.

سطح	محدودیت	کاربرد
ناشناس	120 req/min	endpointهای خواندنی عمومی
جستجو	60 req/min	جستجو و دریافت فایل
احراز هویت‌شده	600 req/min	عملیات کاربر (وارد شده)

هدرهای پاسخ

X-RateLimit-Limit — حداکثر درخواست در هر پنجره

X-RateLimit-Remaining — درخواست‌های باقی‌مانده در پنجره فعلی

X-RateLimit-Reset — برچسب زمانی Unix برای بازنشانی پنجره

پاسخ‌های خطا

تمام خطاها از فرمت JSON یکسان پیروی می‌کنند.

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retryAfter": 45,
  "limit": 60
}

کدهای وضعیت رایج

400 — درخواست نامعتبر — پارامترهای گم‌شده یا نادرست

401 — غیرمجاز — احراز هویت لازم است

404 — یافت نشد — منبع وجود ندارد

429 — درخواست بیش از حد — محدودیت نرخ

500 — خطای داخلی سرور

Quick Example

curl "https://skills.palebluedot.live/api/skills?q=code-review&limit=5"

مهارت‌ها

جستجو، مرور و دریافت اطلاعات مهارت‌ها

جستجوی مهارت‌ها با جستجوی متنی، فیلتر و صفحه‌بندی

دریافت اطلاعات کامل یک مهارت

دریافت مهارت‌های برگزیده و محبوب

دریافت مهارت‌های اخیراً اضافه یا به‌روزشده

ثبت نصب یک مهارت

درخواست افزودن مهارت جدید به فهرست

درخواست حذف مهارتی که مالک آن هستید

فایل‌های مهارت

دریافت محتوای فایل و دانلود به صورت ZIP

دریافت تمام فایل‌های پوشه مهارت با محتوا

دانلود فایل‌های مهارت به صورت آرشیو ZIP

عملیات کاربر

امتیازدهی، علاقه‌مندی‌ها و مدیریت مهارت‌ها

دریافت امتیازها و نظرات یک مهارت

ایجاد یا به‌روزرسانی امتیاز شما برای یک مهارت

دریافت امتیاز خودتان برای یک مهارت

دریافت لیست مهارت‌های مورد علاقه شما

افزودن مهارت به علاقه‌مندی‌ها

حذف مهارت از علاقه‌مندی‌ها

بررسی وضعیت علاقه‌مندی مهارت‌ها

کشف و فراداده

دسته‌بندی‌ها، آمار و سلامت سیستم

دریافت تمام دسته‌بندی‌ها با تعداد مهارت

دریافت آمار کلی بازار

بررسی سلامت API و سرویس‌ها

دریافت آمار انتساب و منابع داده

خبرنامه

عضویت و لغو عضویت خبرنامه

عضویت ایمیل در خبرنامه

لغو عضویت ایمیل از خبرنامه