ClawHub Public REST API v1 Overview and Conventions

API v1

Base: https://clawhub.ai

OpenAPI: /api/v1/openapi.json

Public catalog reuse

ClawHub's public read APIs let you create your own catalog, directory, or search interface for third-party use. Public skill metadata and files are distributed according to ClawHub's skill licensing terms. The API itself enforces rate limits, so consume it responsibly.

Guidelines:

• For building catalog listings, use public read endpoints like GET /api/v1/skills, GET /api/v1/search, and GET /api/v1/skills/{slug}.
• Cache API responses and honor 429, Retry-After, and rate-limit headers rather than polling frequently.
• When displaying listings, include a link back to the canonical ClawHub skill page so users can view the original registry entry.
• Canonical page URLs must follow the pattern https://clawhub.ai/<owner>/skills/<slug>.
• Do not suggest that ClawHub endorses, verifies, or runs the third-party site.
• Do not expose hidden, private, or moderation-blocked content by circumventing public API filters or authentication boundaries.

Auth

• Public reads: no token required.
• Writes and account operations: Authorization: Bearer clh_....

Rate limits

Rate limiting depends on authentication:

• Anonymous requests are limited by IP address.

• Authenticated requests (valid Bearer token) are limited per user bucket.

• Missing or invalid tokens revert to IP-based enforcement.

• Read: 3000 per minute per IP, 12000 per minute per key

• Write: 300 per minute per IP, 3000 per minute per key

• Download: 1200 per minute per IP, 6000 per minute per key

Headers: X-RateLimit-Limit, X-RateLimit-Reset, RateLimit-Limit, RateLimit-Reset; X-RateLimit-Remaining, RateLimit-Remaining, and Retry-After appear on 429.

Semantics:

• X-RateLimit-Reset: absolute reset time in Unix epoch seconds
• RateLimit-Reset: seconds remaining until the reset
• X-RateLimit-Remaining / RateLimit-Remaining: exact remaining quota when provided; successful sharded requests omit this rather than returning a global approximation
• Retry-After: seconds to wait on 429

Example 429:

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

Client behavior:

• When Retry-After is available, prefer it.
• Otherwise fall back to RateLimit-Reset or compute a delay from X-RateLimit-Reset.
• Add jitter to retry logic.

Errors

• v1 errors are plain text (text/plain; charset=utf-8), covering 400, 401, 403, 404, 429, and blocked download responses.
• Unknown query parameters are silently ignored for compatibility.
• Known query parameters with invalid values produce 400.

Endpoints

Public read:

• GET /api/v1/search?q=...
  • Non-mandatory filters: highlightedOnly=true, nonSuspiciousOnly=true
  • Previous name: nonSuspicious=true
• GET /api/v1/skills?limit=&cursor=&sort=
  • sort: updated (default), recommended (default), createdAt (newest), downloads, stars (rating), older install aliases installsCurrent/installs/installsAllTime resolve to downloads, trending
  • An incorrect sort value triggers a 400 response
  • cursor only works with sorts other than trending
  • Optional filter: nonSuspiciousOnly=true
  • Previous name: nonSuspicious=true
  • When nonSuspiciousOnly=true is active, cursor-based pages might deliver fewer than limit items; keep going with nextCursor.
  • recommended relies on interaction and freshness metrics.
• 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 hosted on the platform produce deterministic ZIP data.
  • GitHub-backed skills that currently have a clean or suspicious scan return a JSON public-github handoff descriptor rather than ClawHub bytes.
• GET /api/v1/skills/export?startDate=&endDate=&limit=&cursor=
  • Hosted skills get exported as stored files.
  • GitHub-backed skills that currently have a clean or suspicious scan get exported as public-github handoff descriptors.
• GET /api/v1/packages?limit=&cursor=&sort=
  • sort: updated (default), recommended, downloads, previous name installs
  • Invalid sort values cause a 400 response
• GET /api/v1/plugins?limit=&cursor=&sort=
  • sort: recommended (default), downloads, updated, previous name 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

Authentication is mandatory:

• POST /api/v1/skills (publish, multipart preferred)
• 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

Restricted to administrators:

• POST /api/v1/users/reserve holds root slugs and private no-release package placeholders for an owner handle.

Legacy

Older /api/* and /api/cli/* endpoints remain accessible. Refer to DEPRECATIONS.md.