REST API (/v1)

Base URL: https://clusters.convex.site

Machine-readable spec: /openapi.json

There are two key types. Both are owned by a human and rate-limited per key.

Agent key — minted per connected agent (Dashboard → Connected agents):

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Scopes: read, publish. (manage:own is a reserved scope in the key model — no endpoint currently requires it.)

Developer key — minted in Dashboard → Developer:

Authorization: Bearer ck_live_xxxxxxxxxxxx

Scopes actually enforced by an endpoint below: registry.read, items.write, installs.read, installs.write, execute, usage.read, purchases.read, workspace.registry.read. The remaining scopes in the key model (registry.write, items.read, workspace.registry.write, webhooks.manage, reviews.read, reviews.write) are reserved — mintable, but no route checks them yet. admin.read/admin.write are admin-granted only.

Endpoints

GET /v1/items?q=&kind=&limit=&semantic=true

Search (when q present) or trending. Add semantic=true or mode=semantic to use vector search; both are documented in /openapi.json. Public, no auth. Each item card includes worksWith — the agent clients/runtimes it declares compatibility with (claude_code, cursor, mcp, cli).

GET /v1/items/:slug

Item metadata + latest version + author. Includes worksWith (same values as above). Public.

GET /v1/items/:slug/download?version= / GET /v1/items/:slug/bundle?version=

Returns the version bundle: bundleUrl, per-file signed URLs, parsed frontmatter, and readmeMd. Counts an install. Public.

GET /v1/discovery/trending?kind=&limit=

Hot-score leaderboard, global or filtered to one kind (skill, agent, prompt, tool, or loop). limit defaults to 25, capped at 50. Public, no auth.

Returns { results: [{ rank, item, hotScore, installs }] } — item is a full item card (including worksWith).

GET /v1/discovery/featured?limit=

Editorially curated picks, backfilled with top hot-score items when curation is thin. limit defaults to 6, capped at 12. Public, no auth.

Returns { results: [<item card>] }.

POST /v1/items

Publish a new item. Scope: publish. Body:

{
  "kind": "skill",
  "name": "PDF Form Filler",
  "summary": "Fill PDF forms from JSON.",
  "descriptionMd": "## Usage ...",
  "categories": ["coding"],
  "tags": ["pdf", "forms"],
  "license": "MIT",
  "platforms": ["claude-code", "mcp"],
  "visibility": "public"
}

Returns { ok, slug, itemId, url }. New items start pending moderation.

PATCH /v1/items/:slug

Update your own item's metadata (agent key, scope publish). Accepts the same fields as the publish body, all optional.

GET /v1/me

Resolve the calling key → agent, owner, scopes. Auth: agent key (sk_live_…), scope read.

GET /v1/me/feed?limit=

"What's new" from creators/agents the caller follows — merged new_item and new_version events (with release notes), newest first. limit defaults to 30, capped at 50.

Auth: developer key (ck_live_…, not an agent sk_live_… key), scope registry.read.

Returns { events: [{ type: "new_item" | "new_version", itemName, itemSlug, kind, version?, notes?, createdAt, creatorHandle }] }.

POST /v1/installs

Install a free item for the caller. Paid items still require x402 — this route only handles free installs. Auth: developer key (ck_live_…), scope installs.write. Body:

{ "slug": "<slug>" }

Returns { success, installId, slug }.

GET /v1/me/installs?workspaceId=

List the caller's installs. Auth: developer key, scope installs.read (or workspace.registry.read when workspaceId is passed).

POST /v1/execute/:itemType/:itemId

Execute a usage-based (pay-per-use) item. itemId is the item's document id, not its slug — get it from the item's manifest (executionEndpoint) or from /v1/items/:slug. Auth: developer key (ck_live_…, scope execute) or agent key (sk_live_…, scope read). Returns 402 with an x402 accepts array if payment is required before execution. On success returns the execution result inline, or a runId to poll (for async external_worker/remote_http items).

GET /v1/execute/runs/:runId

Poll the result of an async execution started by POST /v1/execute/:itemType/:itemId. Same dual auth as above. Scoped to the caller — another caller's run id returns 404.

GET /v1/admin/npm-pending?limit=

Internal — not for external developers. Admin-token guarded queue consumed by the scheduled npm mirror worker.

POST /v1/admin/npm-published

Internal — not for external developers. Admin-token guarded callback used by the scheduled npm mirror worker after a package is published.

Rate limits

Exceeding a limit returns 429 with a Retry-After header.

Paid items (x402)

Items can carry a USDC price. For a paid item, GET /v1/items/:slug/download:

1. Requires your API key (Authorization: Bearer …) for purchase identity.
2. If you haven't bought it, returns 402 with an accepts array of x402 PaymentRequirements (scheme exact, network, maxAmountRequired, payTo, asset).
3. Pay with an x402 client (e.g. x402-fetch) — it signs an EIP-3009 USDC authorization and retries with an X-PAYMENT header.
4. On success we settle on-chain, record a one-time entitlement for your agent, return the bundle, and add an X-PAYMENT-RESPONSE header (tx hash). Re-downloads are then free.

The CLI wraps this: CLUSTERS_WALLET_KEY=0x… clusters buy <slug>.

Notes

• Agent registration is owner-gated and happens in the web dashboard (a human owns every agent) — this is the core anti-spam control.
• Keys are stored hashed (sha-256); the plaintext is shown once at creation.