Plugin Builder

Public API

Seven HTTP endpoints let you script the builder from a CI job, a community linter, a browser-based dashboard, or any other tool. JSON endpoints are rate-limited to 20 req/min per IP and accept bodies up to 256 KB; /api/parse accepts ZIPs up to 5 MB. Every endpoint sets Access-Control-Allow-Origin: * and responds to OPTIONS preflight, so you can call them from a browser context without a proxy. X-RateLimit-* response headers let polite callers back off before they hit a 429.

POST /api/validate

Run the builder validation ruleset against a plugin spec.

Request body
{
  "plugin": { "name": "pr-workflow", "version": "1.0.0", "description": "...", "skills": [...] }
}
Response
{ "ok": true, "errors": [], "warnings": [...] }
curl
curl -X POST https://pluginbuilder.ai/api/validate \
  -H 'content-type: application/json' \
  --data-binary @plugin.json
POST /api/generate

Generate a plugin ZIP from a spec. Target defaults to Claude Code.

Request body
{
  "plugin": { "name": "pr-workflow", ... },
  "target": "claude-code" | "codex" | "all"
}
Response
application/zip (Content-Disposition: attachment)
curl
curl -X POST https://pluginbuilder.ai/api/generate \
  -H 'content-type: application/json' \
  --data-binary @plugin.json \
  -o pr-workflow.zip
POST /api/digest

Render a plugin spec as a single Markdown digest for sharing.

Request body
{ "plugin": { "name": "pr-workflow", ... } }
Response
text/markdown
curl
curl -X POST https://pluginbuilder.ai/api/digest \
  -H 'content-type: application/json' \
  --data-binary @plugin.json \
  -o digest.md
POST /api/parse

Inverse of /api/generate — POST a plugin ZIP, get the parsed Plugin spec back.

Request body
application/zip (raw bytes, ≤ 5 MB)
Response
{ "plugin": Plugin, "warnings": string[] }
curl
curl -X POST https://pluginbuilder.ai/api/parse \
  -H 'content-type: application/zip' \
  --data-binary @plugin.zip
GET /api/import?repo=owner/repo

Proxy a GitHub repo tarball so you can import plugins by URL.

Response
application/zip (GitHub codeload tarball)
curl
curl -sf 'https://pluginbuilder.ai/api/import?repo=anthropics/example-plugin' \
  -o plugin.zip
GET /api/schema.json

JSON Schema (Draft 2020-12) for plugin.json. Attach via $schema for editor autocomplete.

Response
application/schema+json
curl
curl -sf https://pluginbuilder.ai/api/schema.json -o plugin.schema.json
GET /api/card.svg

Dynamic OG install card. Drop into README badges or link previews.

Response
image/svg+xml (1200×630, cached 1h)
curl
curl -sf 'https://pluginbuilder.ai/api/card.svg?name=pr-workflow&desc=Automates%20PR%20review&skills=3' \
  -o card.svg

TypeScript SDK

A zero-dependency TypeScript SDK is published at /sdk.ts. Drop it into any Bun / Node 18+ / Deno / browser project:

import { PluginBuilder } from 'https://pluginbuilder.ai/sdk.ts';
const pb = new PluginBuilder();
const { ok } = await pb.validate(spec);
if (ok) await Bun.write('plugin.zip', await pb.generate(spec));

Rate limits

All endpoints share a per-IP in-memory limit of 20 requests per minute and reject bodies over 256 KB with a 413. /api/import is additionally capped at 25 MB of upstream response. Over the limit you'll see a 429 with { error: "rate_limited" } — retry after a minute.