API v1

आधार: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

सार्वजनिक कैटलॉग पुन: उपयोग

आप ClawHub के सार्वजनिक रीड API के ऊपर कोई तृतीय-पक्ष कैटलॉग, डायरेक्टरी, या खोज सतह बना सकते हैं। सार्वजनिक skill मेटाडेटा और skill फ़ाइलें ClawHub के skill लाइसेंस नियमों के तहत प्रकाशित की जाती हैं, जबकि API स्वयं दर-सीमित है और इसका उपयोग जिम्मेदारी से किया जाना चाहिए।

दिशानिर्देश:

• कैटलॉग सूचियों के लिए सार्वजनिक रीड एंडपॉइंट जैसे GET /api/v1/skills, GET /api/v1/search, और GET /api/v1/skills/{slug} का उपयोग करें।
• आक्रामक पोलिंग करने के बजाय प्रतिक्रियाओं को कैश करें और 429, Retry-After, और दर-सीमा हेडरों का सम्मान करें।
• सूचियाँ दिखाते समय कैननिकल ClawHub skill URL पर वापस लिंक करें ताकि उपयोगकर्ता स्रोत रजिस्ट्री रिकॉर्ड का निरीक्षण कर सकें।
• https://clawhub.ai/<owner>/skills/<slug> रूप में कैननिकल पेज URL का उपयोग करें।
• यह संकेत न दें कि ClawHub तृतीय-पक्ष साइट का समर्थन, सत्यापन, या संचालन करता है।
• सार्वजनिक API फ़िल्टर या प्रमाणीकरण सीमाओं को बायपास करके छिपी, निजी, या मॉडरेशन-रोकी गई सामग्री को मिरर न करें।

प्रमाणीकरण

• सार्वजनिक रीड: कोई टोकन आवश्यक नहीं।
• राइट + खाता: Authorization: Bearer clh_...।

दर सीमाएँ

प्रमाणीकरण-सचेत प्रवर्तन:

• अनाम अनुरोध: प्रति IP।

• प्रमाणीकृत अनुरोध (मान्य Bearer टोकन): प्रति उपयोगकर्ता बकेट।

• अनुपस्थित/अमान्य टोकन IP प्रवर्तन पर वापस चला जाता है।

• रीड: 3000/min प्रति IP, 12000/min प्रति key

• राइट: 300/min प्रति IP, 3000/min प्रति key

• डाउनलोड: 1200/min प्रति IP, 6000/min प्रति key

हेडर: X-RateLimit-Limit, X-RateLimit-Reset, RateLimit-Limit, RateLimit-Reset; X-RateLimit-Remaining, RateLimit-Remaining, और Retry-After 429 पर शामिल होते हैं।

अर्थ:

• X-RateLimit-Reset: Unix epoch सेकंड (निरपेक्ष रीसेट समय)
• 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 से विलंब निकालें।
• पुनर्प्रयासों में जिटर जोड़ें।

त्रुटियाँ

• v1 त्रुटियाँ सादा पाठ (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 sort पर लागू होता है
  • वैकल्पिक फ़िल्टर: nonSuspiciousOnly=true
  • लेगेसी उपनाम: nonSuspicious=true
  • nonSuspiciousOnly=true के साथ, cursor-आधारित पेजों में 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 बाइट्स लौटाती हैं।
  • वर्तमान GitHub-समर्थित skills जिनका clean या suspicious scan है, ClawHub बाइट्स के बजाय JSON public-github हैंडऑफ़ वर्णनकर्ता लौटाती हैं।
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
  • होस्ट की गई skills संग्रहीत फ़ाइलों के रूप में निर्यात की जाती हैं।
  • वर्तमान GitHub-समर्थित skills जिनका clean या suspicious scan है, 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 (प्रकाशित करें, multipart पसंदीदा)
• 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 किसी owner handle के लिए root slugs और निजी no-release package placeholders आरक्षित करता है।

लेगेसी

लेगेसी /api/* और /api/cli/* अभी भी उपलब्ध हैं। DEPRECATIONS.md देखें।