English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Get started

API v1

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 による適用にフォールバックします。

  • 読み取り: IP ごとに 3000/分、キーごとに 12000/分

  • 書き込み: IP ごとに 300/分、キーごとに 3000/分

  • ダウンロード: IP ごとに 1200/分、キーごとに 6000/分

ヘッダー: X-RateLimit-Limit、X-RateLimit-Reset、RateLimit-Limit、RateLimit-Reset; X-RateLimit-Remaining、RateLimit-Remaining、Retry-After は 429 に含まれます。

セマンティクス:

  • X-RateLimit-Reset: Unix エポック秒（絶対リセット時刻）
  • RateLimit-Reset: リセットまでの遅延秒数
  • X-RateLimit-Remaining / RateLimit-Remaining: 存在する場合は正確な残り予算。シャーディングされた成功リクエストでは、近似のグローバル値を返すのではなく省略されます
  • Retry-After: 429 で待機する遅延秒数

429 の例:

http
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 エラーは 400、401、403、404、429、およびブロックされたダウンロードレスポンスを含め、プレーンテキスト（text/plain; charset=utf-8）です。
  • 不明なクエリパラメーターは互換性のため無視されます。
  • 既知のクエリパラメーターに無効な値がある場合は 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 バイトを返します。
    • 現在の GitHub バックの Skills で clean または suspicious のスキャンがあるものは、ClawHub バイトの代わりに JSON の public-github ハンドオフ記述子を返します。
  • GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
    • ホストされた Skills は保存済みファイルとしてエクスポートされます。
    • 現在の GitHub バックの Skills で 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（公開、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 はオーナーハンドル用にルート slug と非公開のリリースなしパッケージプレースホルダーを予約します。

レガシー

レガシーの /api/* と /api/cli/* は引き続き利用できます。DEPRECATIONS.md を参照してください。

Was this useful?
On this page

On this page