OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

はじめに

API v1

API v1

ベース: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

公開カタログの再利用

ClawHub の公開読み取り API を基盤として、サードパーティのカタログ、ディレクトリ、または検索インターフェースを構築できます。公開されている Skills のメタデータとファイルは ClawHub の Skills ライセンス規則に従って公開されています。一方、API 自体にはレート制限があるため、責任を持って使用してください。

ガイドライン:

  • カタログ一覧には、GET /api/v1/skills、GET /api/v1/search、GET /api/v1/skills/{slug} などの公開読み取りエンドポイントを使用します。
  • 頻繁なポーリングは避け、レスポンスをキャッシュし、429、Retry-After、およびレート制限ヘッダーに従います。
  • 一覧を表示する際は、ユーザーがソースレジストリのレコードを確認できるように、正規の ClawHub Skills URL へのリンクを設定します。
  • ページの正規 URL には https://clawhub.ai/<owner>/skills/<slug> の形式を使用します。
  • 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 のエラーはプレーンテキスト（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 バイト列を返します。
    • clean または suspicious のスキャン結果を持つ現在の GitHub ベースの Skills は、ClawHub のバイト列ではなく、 JSON の public-github 引き継ぎ記述子を返します。
  • GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
    • ホストされている Skills は、保存されているファイルのままエクスポートされます。
    • clean または suspicious のスキャン結果を持つ現在の GitHub ベースの Skills は、 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 は、所有者のハンドル用にルートスラッグと非公開のリリースなしパッケージプレースホルダーを予約します。

レガシー

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

Was this useful?
On this page

On this page