Developers

Planes is a shadcn-style registry of animated React components. There is no SDK to install and no runtime package: every endpoint returns shadcn registry JSON that the shadcn CLI writes into a project as editable source. The whole public surface is described in an OpenAPI 3.1 document at https://useplanes.com/openapi.json, and this page is the human-readable companion to it.

Two registries exist. The free registry is static JSON under /r and needs no credentials. The Pro registry at /api/registry/{name} serves the same shape but checks a Planes Pro license key on every request.

List the free components, then install one. No account needed:

curl https://useplanes.com/r/index.json
npx shadcn add https://useplanes.com/r/segmented-control.json

For Pro components, configure the @useplanes registry once with the CLI, then install by name:

npx @useplanes/cli init --key <your_license_key>
npx shadcn add @useplanes/command-palette

The only credential is a Planes Pro license key, issued by Polar at purchase and delivered by email. Send it as a bearer token: Authorization: Bearer <license_key>. There are no separate API keys to create; the license key is the API key. Buy one at https://useplanes.com/#pricing, check one at https://useplanes.com/setup, and manage seats in the Polar customer portal linked from your purchase email.

POST /api/validate reports whether a key is valid without consuming a seat. POST /api/activate registers a seat (a machine or project) against the key; installs do not require it, but setup scripts may use it. Neither endpoint ever echoes the key back.

GET /r/index.json — free registry index (operationId listFreeComponents).

GET /r/{slug}.json — a free component with file contents (getFreeComponent).

GET /api/registry/registry — Pro registry index, metadata only, no auth (listProComponents).

GET /api/registry/{name} — a Pro component with file contents, bearer auth (getProComponent).

POST /api/validate — check a license key (validateLicenseKey).

POST /api/activate — activate a seat on a license key (activateLicenseKey).

GET /api/checkout — redirect to Polar checkout for Planes Pro (createCheckout).

Parameters, request bodies, and response schemas for each are in https://useplanes.com/openapi.json.

Every error is JSON with the same shape: a human-readable error, a stable machine-readable code, an optional hint describing how to recover, and a docs link back to this page. Unknown /api paths return this shape with a 404 rather than an HTML page.

{
  "error": "Missing license key. Get one at https://useplanes.com/#pricing ...",
  "code": "license_required",
  "hint": "Send the key as `Authorization: Bearer <license_key>`.",
  "docs": "https://useplanes.com/developers"
}

Codes: not_found, rate_limited, invalid_json, missing_license_key, malformed_license_key, license_required (401), license_invalid (403), license_not_found, activation_limit_reached, activation_failed, upstream_unavailable (502), unknown_product, not_configured.

Rate limits are per IP (30 requests per minute) with a tighter per-key bucket (10 per minute) on the license endpoints. A 429 carries a Retry-After header in seconds.

@useplanes/cli on npm adds the @useplanes registry to components.json, writes PLANES_LICENSE_KEY to .env.local, keeps it gitignored, and verifies the key. Flags: --key, --url, --no-verify, and -y for non-interactive use. Running it again updates the entry in place.

npx @useplanes/cli init --key <your_license_key> -y

Planes does not run its own MCP server; the shadcn CLI ships one that exposes every registry in components.json, including @useplanes once configured. Setup is on the MCP page at https://useplanes.com/components/mcp. Agents reading without tools should start at https://useplanes.com/llms.txt (index) and https://useplanes.com/llms-full.txt (usage and props for every component). Pages with a markdown twin, including this one, return it for Accept: text/markdown.

There is no separate sandbox environment: the free registry is fully functional without credentials and exercises the same install path as Pro. Questions about integrating go to ashish@ashishgogula.in.