ClawHub HTTP endpoints

An endpoint list is usually the dullest page in a registry's documentation. ClawHub's is worth reading closely, because several of its endpoints answer differently depending on who is asking, and one of them does not return the file you asked for.

The public reads

• Search takes a query with optional filters for highlighted and non-suspicious listings and an exact mode for deterministic slug matches, and an unrecognised mode returns 400 rather than quietly falling back.
• The skills listing paginates by cursor and accepts a sort of updated, recommended, newest, downloads, stars, name or trending, with an invalid sort returning 400 and the cursor applying to everything except trending.
• A prefix parameter gives a deterministic slug-prefix listing in ascending order, continued through the returned cursor, which is the shape a mirror wants rather than a relevance sort.
• Per-skill reads cover the record itself, its moderation state, its version list, a single version, its scan result and an individual file from the bundle.

Public callers only get 200 for already-flagged visible skills.

A record that redacts itself

The moderation endpoint returns a structured verdict with reason codes, a summary, the engine version and an array of evidence. What changes with the caller is how much of that evidence survives. Owners and moderators can read moderation details for hidden skills and receive the raw snippets, while public callers are given a redacted form, and only for skills that are already flagged and still visible. A stranger cannot use the endpoint to discover a problem that has not been published yet.

The download that is not bytes

• A hosted skill downloads as deterministic ZIP bytes, which is what makes a fingerprint comparison meaningful on the client side.
• A current GitHub-backed skill whose scan is clean or suspicious returns a JSON handoff descriptor instead of ClawHub bytes, so a client must be ready for either shape from the same endpoint.
• The bulk export follows exactly the same rule, exporting hosted skills as stored files and GitHub-backed ones as handoff descriptors.

Verification has its own endpoint returning the Skill Card envelope, and it is stricter than it looks. The result is reported as ok only when the selected version has a generated Skill Card, is not blocked as malware by moderation, and carries a clean scan verdict, so two of the three conditions have nothing to do with the code itself. Identity and version fields sit at the top level of the envelope so shell automation can read them without unpacking a wrapper. See The ClawHub API for the conventions every one of these endpoints shares, and How ClawHub works for what the records describe.

What automation should ask for

The verification envelope carries the complete upstream scanner reports, with nothing truncated, and they are included by default. That makes the response substantially larger than most callers need, so a CI job should select only the verdict fields it will act on rather than storing the whole envelope. Each raw report is null when it was not retained for that scan, which means an older scan needs a rescan rather than a retry, and reports are withheld while a rescan is committing if they no longer match the stored summaries. Reporting a listing for review is a separate endpoint and needs a token. See Reporting a ClawHub vulnerability for where a report belongs and The ClawHub CLI for the client that calls most of this.

On Diali

Diali hosts OpenClaw, and the client that calls most of these endpoints ships with it. Each customer runs their own assistant, 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.

• Several endpoints answer differently depending on who asks.
• A download can return a descriptor; handle both shapes.
• Select the verdict fields in CI, not the whole envelope.