API نسخه ۱

پایه: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

استفادهٔ مجدد از کاتالوگ عمومی

می‌توانید با استفاده از APIهای خواندنی عمومی ClawHub، یک کاتالوگ، فهرست یا رابط جست‌وجوی شخص ثالث بسازید. فراداده‌ها و فایل‌های عمومی Skills طبق قواعد مجوز Skills در ClawHub منتشر می‌شوند، درحالی‌که خود API دارای محدودیت نرخ است و باید مسئولانه از آن استفاده شود.

رهنمودها:

• برای فهرست‌های کاتالوگ، از نقطه‌های پایانی خواندنی عمومی مانند GET /api/v1/skills، GET /api/v1/search و GET /api/v1/skills/{slug} استفاده کنید.
• به‌جای نظرسنجی مکرر، پاسخ‌ها را ذخیره کنید و به 429، Retry-After و سرآیندهای محدودیت نرخ احترام بگذارید.
• هنگام نمایش فهرست‌ها، به نشانی متعارف Skill در ClawHub پیوند دهید تا کاربران بتوانند رکورد رجیستری منبع را بررسی کنند.
• از نشانی‌های متعارف صفحه با قالب https://clawhub.ai/<owner>/skills/<slug> استفاده کنید.
• این تصور را ایجاد نکنید که ClawHub وب‌سایت شخص ثالث را تأیید، راستی‌آزمایی یا اداره می‌کند.
• با دور زدن فیلترهای API عمومی یا مرزهای احراز هویت، محتوای پنهان، خصوصی یا مسدودشده توسط نظارت را آینه‌سازی نکنید.

احراز هویت

• خواندن عمومی: نیازی به توکن ندارد.
• نوشتن + حساب: Authorization: Bearer clh_....

محدودیت‌های نرخ

اعمال آگاه از احراز هویت:

• درخواست‌های ناشناس: به‌ازای هر IP.

• درخواست‌های احرازشده (توکن Bearer معتبر): به‌ازای هر سبد کاربر.

• توکن مفقود یا نامعتبر به اعمال محدودیت بر اساس IP بازمی‌گردد.

• خواندن: 3000/دقیقه به‌ازای هر IP، 12000/دقیقه به‌ازای هر کلید

• نوشتن: 300/دقیقه به‌ازای هر IP، 3000/دقیقه به‌ازای هر کلید

• دانلود: 1200/دقیقه به‌ازای هر IP، 6000/دقیقه به‌ازای هر کلید

سرآیندها: X-RateLimit-Limit، X-RateLimit-Reset، RateLimit-Limit، RateLimit-Reset؛ X-RateLimit-Remaining، RateLimit-Remaining و Retry-After در 429 گنجانده می‌شوند.

معناشناسی:

• X-RateLimit-Reset: ثانیه‌های دورهٔ یونیکس (زمان مطلق بازنشانی)
• RateLimit-Reset: مدت تأخیر برحسب ثانیه تا بازنشانی
• X-RateLimit-Remaining / RateLimit-Remaining: بودجهٔ دقیق باقی‌مانده در صورت وجود؛ درخواست‌های موفق بخش‌بندی‌شده به‌جای بازگرداندن یک مقدار تقریبی سراسری، آن را حذف می‌کنند
• Retry-After: مدت تأخیر برحسب ثانیه برای انتظار در 429

نمونهٔ 429:

HTTP/2 429x-ratelimit-limit: 20x-ratelimit-remaining: 0x-ratelimit-reset: 1771404540ratelimit-limit: 20ratelimit-remaining: 0ratelimit-reset: 34retry-after: 34

مدیریت سمت کلاینت:

• در صورت وجود، Retry-After را ترجیح دهید.
• در غیر این صورت، از RateLimit-Reset استفاده کنید یا تأخیر را از X-RateLimit-Reset محاسبه کنید.
• به تلاش‌های مجدد جیتر اضافه کنید.

خطاها

• خطاهای نسخهٔ ۱ متن ساده هستند (text/plain; charset=utf-8)، از جمله 400، 401، 403، 404، 429 و پاسخ‌های دانلود مسدودشده.
• پارامترهای پرس‌وجوی ناشناخته برای سازگاری نادیده گرفته می‌شوند.
• پارامترهای پرس‌وجوی شناخته‌شده با مقادیر نامعتبر، 400 را بازمی‌گردانند.

نقطه‌های پایانی

خواندن عمومی:

• GET /api/v1/search?q=...
  • فیلترهای اختیاری: highlightedOnly=true، nonSuspiciousOnly=true
  • نام مستعار قدیمی: nonSuspicious=true
• GET /api/v1/skills?limit=&cursor=&sort=
  • sort: updated (پیش‌فرض)، recommended (default)، createdAt (newest)، downloads، stars (rating)، نام‌های مستعار قدیمی نصب installsCurrent/installs/installsAllTime به downloads، trending نگاشت می‌شوند
  • مقادیر نامعتبر sort، 400 را بازمی‌گردانند
  • cursor برای مرتب‌سازی‌های غیر trending اعمال می‌شود
  • فیلتر اختیاری: nonSuspiciousOnly=true
  • نام مستعار قدیمی: nonSuspicious=true
  • با nonSuspiciousOnly=true، صفحه‌های مبتنی بر مکان‌نما ممکن است کمتر از limit مورد داشته باشند؛ برای ادامه از nextCursor استفاده کنید.
  • recommended از سیگنال‌های تعامل و تازگی استفاده می‌کند.
• GET /api/v1/skills/{slug}
• GET /api/v1/skills/{slug}/moderation
• GET /api/v1/skills/{slug}/versions?limit=&cursor=
• GET /api/v1/skills/{slug}/versions/{version}
• GET /api/v1/skills/{slug}/scan?version=&tag=
• GET /api/v1/skills/{slug}/file?path=&version=&tag=
• GET /api/v1/resolve?slug=&hash=
• GET /api/v1/download?slug=&version=&tag=
  • Skills میزبانی‌شده، بایت‌های ZIP قطعی بازمی‌گردانند.
  • Skills فعلی مبتنی بر GitHub با اسکن clean یا suspicious، به‌جای بایت‌های ClawHub یک توصیف‌گر واگذاری JSON با public-github بازمی‌گردانند.
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
  • Skills میزبانی‌شده به‌شکل فایل‌های ذخیره‌شده صادر می‌شوند.
  • Skills فعلی مبتنی بر GitHub با اسکن clean یا suspicious، به‌شکل توصیف‌گرهای واگذاری public-github صادر می‌شوند.
• GET /api/v1/packages?limit=&cursor=&sort=
  • sort: updated (پیش‌فرض)، recommended، downloads، نام مستعار قدیمی installs
  • مقادیر نامعتبر sort، 400 را بازمی‌گردانند
• GET /api/v1/plugins?limit=&cursor=&sort=
  • sort: recommended (پیش‌فرض)، downloads، updated، نام مستعار قدیمی installs
• GET /api/v1/plugins/search?q=...
• GET /api/v1/packages/{name}/versions/{version}/artifact
• GET /api/v1/packages/{name}/versions/{version}/security
• GET /api/v1/packages/{name}/versions/{version}/artifact/download
• GET /api/npm/{package}
• GET /api/npm/{package}/-/{tarball}.tgz

نیازمند احراز هویت:

• POST /api/v1/skills (انتشار، چندبخشی ترجیح داده می‌شود)
• DELETE /api/v1/skills/{slug}
• DELETE /api/v1/packages/{name}
• POST /api/v1/skills/{slug}/undelete
• POST /api/v1/packages/{name}/undelete
• POST /api/v1/skills/{slug}/rename
• POST /api/v1/skills/{slug}/merge
• POST /api/v1/skills/{slug}/transfer
• POST /api/v1/packages/{name}/transfer
• POST /api/v1/skills/{slug}/transfer/accept
• POST /api/v1/skills/{slug}/transfer/reject
• POST /api/v1/skills/{slug}/transfer/cancel
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
• GET /api/v1/plugins/export?startDate=&endDate=&limit=&cursor=&family=
• GET /api/v1/transfers/incoming
• GET /api/v1/transfers/outgoing
• GET /api/v1/whoami

فقط مدیر:

• POST /api/v1/users/reserve نامک‌های ریشه و جای‌نگهدارهای خصوصی بستهٔ بدون انتشار را برای شناسهٔ مالک رزرو می‌کند.

قدیمی

/api/* و /api/cli/* قدیمی همچنان در دسترس هستند. DEPRECATIONS.md را ببینید.