clawhub/docs/http-api.md

summary	read_when
HTTP API reference (public + CLI endpoints + auth).	Adding/changing endpoints Debugging CLI ↔ registry requests

HTTP API

Base URL: https://clawdhub.com (default).

All v1 paths are under /api/v1/... and implemented by Convex HTTP routes (convex/http.ts). Legacy /api/... and /api/cli/... remain for compatibility (see DEPRECATIONS.md). OpenAPI: /api/v1/openapi.json.

Rate limits

Enforced per IP + per API key:

• Read: 120/min per IP, 600/min per key
• Write: 30/min per IP, 120/min per key

Headers:

• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (when limited)

Public endpoints (no auth)

GET /api/v1/search

Query params:

• q (required): query string
• limit (optional): integer
• highlightedOnly (optional): true to filter to highlighted skills

Response:

{ "results": [{ "score": 0.123, "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "version": "1.2.3", "updatedAt": 1730000000000 }] }

GET /api/v1/skills

Query params:

• limit (optional): integer (1–200)
• cursor (optional): pagination cursor (only for sort=updated)
• sort (optional): updated (default), downloads, stars (alias: rating), installsCurrent (alias: installs), installsAllTime, trending

Notes:

• trending ranks by installs in the last 7 days (telemetry-based).

Response:

{ "items": [{ "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "tags": { "latest": "1.2.3" }, "stats": {}, "createdAt": 0, "updatedAt": 0, "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" } }], "nextCursor": null }

GET /api/v1/skills/{slug}

Response:

{ "skill": { "slug": "gifgrep", "displayName": "GifGrep", "summary": "…", "tags": { "latest": "1.2.3" }, "stats": {}, "createdAt": 0, "updatedAt": 0 }, "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" }, "owner": { "handle": "steipete", "displayName": "Peter", "image": null } }

GET /api/v1/skills/{slug}/versions

Query params:

• limit (optional): integer
• cursor (optional): pagination cursor

GET /api/v1/skills/{slug}/versions/{version}

Returns version metadata + files list.

GET /api/v1/skills/{slug}/file

Returns raw text content.

Query params:

• path (required)
• version (optional)
• tag (optional)

Notes:

• Defaults to latest version.
• File size limit: 200KB.

GET /api/v1/resolve

Used by the CLI to map a local fingerprint to a known version.

Query params:

• slug (required)
• hash (required): 64-char hex sha256 of the bundle fingerprint

Response:

{ "slug": "gifgrep", "match": { "version": "1.2.2" }, "latestVersion": { "version": "1.2.3" } }

GET /api/v1/download

Downloads a zip of a skill version.

Query params:

• slug (required)
• version (optional): semver string
• tag (optional): tag name (e.g. latest)

Notes:

• If neither version nor tag is provided, the latest version is used.
• Soft-deleted versions return 410.

Auth endpoints (Bearer token)

All endpoints require:

Authorization: Bearer clh_...

GET /api/v1/whoami

Validates token and returns the user handle.

POST /api/v1/skills

Publishes a new version.

• Preferred: multipart/form-data with payload JSON + files[] blobs.
• JSON body with files (storageId-based) is also accepted.

DELETE /api/v1/skills/{slug} / POST /api/v1/skills/{slug}/undelete

Soft-delete / restore a skill (owner/admin only).

POST /api/v1/stars/{slug} / DELETE /api/v1/stars/{slug}

Add/remove a star (highlights). Both endpoints are idempotent.

Responses:

{ "ok": true, "starred": true, "alreadyStarred": false }

{ "ok": true, "unstarred": true, "alreadyUnstarred": false }

Legacy CLI endpoints (deprecated)

Still supported for older CLI versions:

• GET /api/cli/whoami
• POST /api/cli/upload-url
• POST /api/cli/publish
• POST /api/cli/telemetry/sync
• POST /api/cli/skill/delete
• POST /api/cli/skill/undelete

See DEPRECATIONS.md for removal plan.

Registry discovery (/.well-known/clawdhub.json)

The CLI can discover registry/auth settings from the site:

• /.well-known/clawdhub.json (JSON)

Schema:

{ "apiBase": "https://clawdhub.com", "authBase": "https://clawdhub.com", "minCliVersion": "0.0.5" }

If you self-host, serve this file (or set CLAWDHUB_REGISTRY explicitly).