188 lines
4.4 KiB
Markdown
188 lines
4.4 KiB
Markdown
---
|
||
summary: 'HTTP API reference (public + CLI endpoints + auth).'
|
||
read_when:
|
||
- 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:
|
||
|
||
```json
|
||
{ "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:
|
||
|
||
```json
|
||
{ "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:
|
||
|
||
```json
|
||
{ "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:
|
||
|
||
```json
|
||
{ "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:
|
||
|
||
```json
|
||
{ "ok": true, "starred": true, "alreadyStarred": false }
|
||
```
|
||
|
||
```json
|
||
{ "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:
|
||
|
||
```json
|
||
{ "apiBase": "https://clawdhub.com", "authBase": "https://clawdhub.com", "minCliVersion": "0.0.5" }
|
||
```
|
||
|
||
If you self-host, serve this file (or set `CLAWDHUB_REGISTRY` explicitly).
|