The ClawHub API

Very few registries say out loud that you may build a competing surface on top of them. ClawHub does, and then spends most of its API documentation on the conditions, which is the honest way round. The base is the registry host itself, and the whole v1 surface is described by an OpenAPI document the client can read directly.

The reuse rules

• The public read endpoints, the skills listing, the search endpoint and the single-skill record, are the intended foundation for a third-party catalogue, directory or search surface.
• Responses should be cached, and 429 responses, the Retry-After header and the rate-limit headers respected, rather than polled against aggressively.
• Listings should link back to the canonical ClawHub page so a reader can inspect the source registry record, using the canonical URL form built from the owner handle and the skill slug.
• Hidden, private and moderation-blocked content must not be mirrored by bypassing the public API filters or the auth boundary.

Do not imply that ClawHub endorses, verifies, or operates the third-party site.

Where the token boundary sits

Public reads need no token at all, which is what makes an independent catalogue practical in the first place. Anything that writes, or that touches an account, needs an authorisation header carrying a bearer token. That single line is the whole auth model, and the rate limiter reads the same token to decide which budget a request spends.

Two budgets, not one

• Anonymous requests are counted per IP address and authenticated requests against a per-user bucket, and a missing or invalid token falls back to IP enforcement rather than being rejected outright.
• Reads allow three thousand a minute per IP and twelve thousand per key, writes three hundred and three thousand, downloads twelve hundred and six thousand, so signing in is worth roughly four times an anonymous address on every class.
• Errors in v1 are plain text rather than JSON, including 400, 401, 403, 404, 429 and blocked-download responses, which is worth knowing before a client tries to parse one as an object.

Unknown query parameters are ignored for compatibility, but a known parameter carrying an invalid value returns 400. A typo in a value therefore fails loudly while a typo in a parameter name fails silently, which is the one asymmetry worth writing a test around. For the endpoint list these conventions apply to, see The ClawHub HTTP endpoints, and for the publishing side of the same registry, What ClawHub checks before publishing.

Reading the retry headers

Two header families carry the same information in two different units, and mixing them up is the usual cause of a retry storm. The prefixed reset header is an absolute Unix epoch second, the unprefixed one is a delay in seconds, and Retry-After on a 429 is also a delay. A client should prefer Retry-After when it is present, fall back to the delay-shaped reset, derive a delay from the absolute value only as a last resort, and add jitter in every case. The remaining-budget headers are exact when present and are omitted rather than approximated on sharded successful requests, so their absence is not a zero. See The ClawHub CLI and Reporting a ClawHub vulnerability for the two surfaces that consume this API most.

On Diali

Diali hosts OpenClaw, and the registry calls described here are made by the assistant on your behalf rather than by you. Each customer runs their own instance, the runtime configuration is generated from the dashboard and replaced at each release, and state lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). See Hosted OpenClaw on Diali for what the hosting includes and Diali pricing for what it costs.

• Public reads need no token; anything that writes does.
• Prefer Retry-After, then the delay-shaped reset, and always add jitter.
• A missing remaining-header is a shard, not a zero.