Developers

REST API reference

Everything BrandPilot produces is also a plain HTTP API under https://brandpilot.dev/api/v1. Published brand systems need no key; your own designs need an API key. The machine-readable description is at /api/v1/openapi.json.

Quick start

# 1. List the published brand systems
curl https://brandpilot.dev/api/v1/systems

# 2. Get one system's manifest (token URLs, components, pages, assets)
curl https://brandpilot.dev/api/v1/systems/{name}/adoption

# 3. Download everything as one ZIP
curl -O https://brandpilot.dev/api/v1/systems/{name}/download

Public endpoints (no key)

Method	Endpoint	Returns
GET	`/api/v1/systems`	The published brand systems, ACTIVE only. Filter: `platform` (NEXTJS, WORDPRESS)
GET	`/api/v1/systems/{name}/adoption`	The manifest: tokens, components, pages, brand assets and export formats
GET	`/api/v1/systems/{name}/download`	A ZIP bundle with every file
GET	`/api/v1/systems/{name}/agent-prompt`	Markdown with copy-paste prompts for your coding agent
GET	`/api/systems/export/{name}?format={format}`	One token or component export (formats below)

Only systems with status ACTIVE have approved, ready-to-use files. A system served by these routes always resolves to one approved design: the one the owner pinned, else the newest published, else the newest approved.

Export formats

format	What you get
`globals-css`	CSS variables in the shadcn/ui shape, light and dark
`colors-ts`	TypeScript color tokens (HEX and HSL)
`tailwind-theme`	Tailwind v3 theme extension
`tailwind-v4`	Tailwind v4 `@theme` CSS with OKLCH colors, fonts, radius and spacing
`dtcg`	W3C Design Tokens Community Group JSON
`brand-manifest`	JSON brand manifest (colors, typography, spacing)
`components`	ZIP of component files
`components-json`	Components as JSON, with HTML code and variants per row
`pages`	ZIP of page template files
`assets-svg`	ZIP of the vector brand assets with a manifest
`all`	ZIP of every token file, component, page and vector asset

ZIP bundle

Bundle contents

{name}-{version}-bundle.zip
  manifest.json          metadata, file list, brand asset URLs
  tokens/
    globals.css          CSS variables
    colors.ts            color tokens
    tailwind-theme.ts    Tailwind config extension
    tailwind-theme.css   Tailwind v4 @theme (OKLCH)
    tokens.dtcg.json     DTCG design tokens
    brand-manifest.json
  components/            one file per component
  pages/                 one file per page template
  ADOPTION_GUIDE.md

Raster brand assets (logo, images) are not inside the ZIP: manifest.json and the adoption manifest list their URLs, with WebP and thumbnail variants where they exist. Download them into your own public/ folder.

Your designs (API key)

These routes take an API key as Authorization: Bearer <key> and only reach designs in the key's own workspace; another workspace's design answers 404.

Method	Endpoint	Permission	Returns
GET	`/api/v1/me`	any	The workspace, key name and permissions
GET	`/api/v1/designs/{id}/handoff`	`READ`	The design as JSON: tokens, direction, mark, imagery, the continuation rules and the import contract
GET	`/api/v1/designs/{id}/handoff-prompt`	`READ`	The same contract as a markdown prompt for a text-first agent
GET	`/api/v1/designs/{id}/prompt-pack`	`READ`	An ordered Claude Design prompt pack built from the design
POST	`/api/v1/designs/{id}/external-artifacts`	`ARTIFACTS_WRITE`	Uploads components, pages and assets as drafts for your review
POST	`/api/v1/designs/{id}/finish-external`	`PIPELINE`	Ends the external design step and moves the project to review

Upload limits: each request body must stay under 4,000,000 bytes (a 413 otherwise). Send components and pages in their own request and each raster asset in its own request, at most 3 MB per asset, or pass an https image URL instead. Uploads land as drafts; nothing is approved without you.

Previews

Approved and published designs have public previews at /preview/d/{designId}, with /components/{name}, /landing and /pricing below it. The adoption manifest carries these links as previewUrl.

Errors, limits and caching

Status	Meaning
400	Invalid parameters
401	Missing, invalid or revoked key
403	The key lacks the permission this route needs
404	Unknown system or design, or one outside your workspace
429	Rate limited; wait for the `Retry-After` header

Errors are JSON, for example { "error": "System 'unknown' not found" }. Token exports are generated on each request; the agent prompt is cached for about 5 minutes and carries an X-System-Updated-At header so you know when to fetch it again.