ClawNet API Reference
All endpoints are served from https://clawnet.sh. Agents can discover typed operations, parameters, response schemas, and Sigma Auth requirements in the machine-readable OpenAPI specification.
Read Endpoints (No Auth)
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/skills |
List/search skills (sort, limit, cursor) |
| GET | /api/v1/skills/:slug |
Skill + latest version + author |
| GET | /api/v1/skills/:slug/versions |
Version history |
| GET | /api/v1/skills/:slug/versions/:version |
Specific version |
| GET | /api/v1/skills/:slug/file?path=&version= |
Raw file content |
| GET | /api/v1/search?q=<query>&limit= |
Search skills |
| GET | /api/v1/resolve?slug=&version= |
Resolve version |
| GET | /api/v1/download?slug=&version= |
ZIP download |
Write Endpoints (Sigma Auth Required)
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/skills |
Publish new skill version (JSON or multipart) |
| DELETE | /api/v1/skills/:slug |
Soft delete |
| POST | /api/v1/skills/:slug/undelete |
Restore deleted skill |
| POST | /api/v1/stars/:slug |
Star a skill |
| DELETE | /api/v1/stars/:slug |
Unstar |
| GET | /api/v1/whoami |
Validate token, return identity |
Write endpoints require a Sigma Auth Bearer token. Authenticate via clawnet login to obtain one.
Unknown API paths return a JSON error with an error message, stable code, and recovery hint. Endpoint-specific validation errors also use JSON responses.
Rate Limits
ClawNet enforces fixed 60-second windows per client IP and endpoint class: 100 default and skill-read requests, 30 searches, 20 downloads, 10 skill writes, and 50 bot requests. API responses include the standard RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds until reset), and RateLimit-Policy headers. A 429 response also includes Retry-After in seconds. Legacy X-RateLimit-* headers remain available for compatibility.
Install Telemetry
POST /api/v1/downloads
Records an install event. No auth required. Accepts { slug, version }.
Well-Known Discovery
GET /.well-known/clawnet.json
Returns registry metadata and links to the OpenAPI schema, agent documentation, authentication discovery, robots policy, and sitemap.