Developers

Migrating to API v2

API v2 is live and covers everything v1 does. v1 keeps working until 14 December 2026 and answers 410 from 15 December 2026. Most callers only change /api/v1 to /api/v2 and switch a design handoff key to an API key.

Why v2

Claude Design (claude.ai/design) closes on 14 December 2026. BrandPilot stays the source of truth for your brand, and the design work moves into Claude Artifacts: each app gets one Design System artifact, and each redesign round gets one Design canvas artifact with one artboard per surface. Claude Code builds them from inside your app's repo. Agents without the Artifact tool, such as Cursor or Codex, build local HTML drafts in the repo instead.

v1 routes and prompts were written around Claude Design projects. v2 serves the same data with the Artifact workflow, so the three routes that describe how to design (the prompt pack, the handoff prompt and the agent prompt) change their content, the Claude Design kit route is renamed, and every other route keeps its response body.

Dates

Date	What happens
22 October 2026	API v2 and the new MCP tool names are live. v1 still answers.
22 October to 14 December 2026	Every v1 response carries `Deprecation`, `Sunset: Tue, 15 Dec 2026 00:00:00 GMT` and `Link: <v2 path>; rel="successor-version"`.
14 December 2026	Claude Design closes. Last day v1 answers.
15 December 2026	Every v1 route answers HTTP 410 `API_V1_RETIRED`. Design handoff keys stop working, and the older MCP tool names stop answering.

Headers on a v1 response until 14 December 2026

Deprecation: @1792627200
Sunset: Tue, 15 Dec 2026 00:00:00 GMT
Link: </api/v2/systems>; rel="successor-version"
Link: </docs/migration-v2>; rel="deprecation"

Any v1 route from 15 December 2026

HTTP/1.1 410 Gone

{
  "error": "API_V1_RETIRED",
  "message": "BrandPilot API v1 was retired on 2026-12-15. Call /api/v2/systems instead; the route table is at /docs/migration-v2.",
  "successor": "/api/v2/systems",
  "docs": "/docs/migration-v2"
}

The successor field and the successor-version link name the exact v2 path for the route you called, with your query string kept, so a client can log it or follow it.

Route table

v1	v2	Notes
`GET /api/v1/systems`	`GET /api/v2/systems`	Same body
`GET /api/v1/systems/{name}/adoption`	`GET /api/v2/systems/{name}/adoption`	Same body; the export URLs inside point at v2
`GET /api/v1/systems/{name}/download`	`GET /api/v2/systems/{name}/download`	Same ZIP
`GET /api/v1/systems/{name}/agent-prompt`	`GET /api/v2/systems/{name}/agent-prompt`	New content: the Design System artifact and the Design canvas for Claude Code, local HTML drafts for other agents
`GET, POST, DELETE /api/v1/systems/{name}/webhooks`	`GET, POST, DELETE /api/v2/systems/{name}/webhooks`	Same bodies; register new subscriptions here
`GET /api/systems/export/{name}?format=`	`GET /api/v2/systems/{name}/export?format=`	Same 15 formats (below)
`GET /api/v1/designs/{id}/handoff`	`GET /api/v2/designs/{id}/handoff`	Same body; the import contract points at v2
`GET /api/v1/designs/{id}/handoff-prompt`	`GET /api/v2/designs/{id}/handoff-prompt`	Always written for an API key
`GET /api/v1/designs/{id}/prompt-pack`	`GET /api/v2/designs/{id}/prompt-pack`	New parameters and content (see below)
`GET /api/v1/designs/{id}/rules-pack`	`GET /api/v2/designs/{id}/rules-pack`	Same body
`GET /api/v1/designs/{id}/claude-design-kit`	`GET /api/v2/designs/{id}/design-system-kit`	Renamed; the same `project/` tree, for a Design System artifact
`GET /api/v1/designs/{id}/brand-book`	`GET /api/v2/designs/{id}/brand-book`	Same file
`GET /api/v1/designs/{id}/deck`	`GET /api/v2/designs/{id}/deck`	Same file
`POST /api/v1/designs/{id}/external-artifacts`	`POST /api/v2/designs/{id}/external-artifacts`	API key only
`POST /api/v1/designs/{id}/finish-external`	`POST /api/v2/designs/{id}/finish-external`	API key only
`GET /api/v1/me`	`GET /api/v2/me`	Same body
`GET /api/v1/mcp/tools`	`GET /api/v2/mcp/tools`	The v2 tool names
`GET /api/v1/openapi.json`	`GET /api/v2/openapi.json`	Describes v2

Export formats on /api/v2/systems/{name}/export: globals-css, colors-ts, tailwind-theme, tailwind-v4, spacing-ts, typography-ts, brand-manifest, dtcg, components, pages, components-json, pages-json, assets-svg, all and tokens.

MCP tool names

The hosted MCP (POST /api/mcp) serves all twelve tools below with a workspace API key. The older names still answer as aliases until 14 December 2026 and stop answering on 15 December 2026. The full, current list is on MCP tools.

Tool	Older name (until 14 December 2026)
`whoami`	Unchanged
`list_brands`	Unchanged
`get_design_context`	`get_design_handoff`
`get_repo_rules_pack`	Unchanged
`get_design_system_kit`	`get_claude_design_kit`
`get_design_brief`	`get_design_prompt_pack`
`import_design_work`	`import_design_artifacts`
`finish_design_import`	`finish_external_design`
`list_public_systems`	`list_systems`
`get_system_manifest`	`get_system_adoption`
`export_system_tokens`	`get_system_tokens`
`get_adoption_brief`	`get_agent_prompt`

The prompt pack in v2

GET /api/v2/designs/{id}/prompt-pack takes agent=claude|other (default claude), pass=explore|lock (default explore), direction (required with lock), round, with3d and format=markdown|json|copy-map. The MCP tool get_design_brief takes the same arguments. The pack names no Claude Design template, project or upload step.

agent=claude: Claude Code, running in your app's repo, installs the app's Design System artifact on one Design canvas per round and builds one artboard per surface. You review and comment on the canvas; nothing is ported into your code until you approve it.
agent=other: Cursor, Codex or any agent without the Artifact tool builds the same brief as local standalone HTML drafts in design/drafts/<round>/, one file per surface, with the same review steps.
pass=explore asks for two or three directions per surface; pass=lock builds every surface in the direction you chose and needs direction.

What does not change

Webhook payloads, headers and signatures. Existing subscriptions keep delivering; only the registration route moves to /api/v2/systems/{name}/webhooks.
Response bodies, apart from URLs inside them that now point at v2. Only the prompt pack, the handoff prompt and the agent prompt are rewritten.
API key permissions: READ, ARTIFACTS_WRITE and PIPELINE gate the same routes and tools as before.
Published brand systems stay public: the system routes need no key.

Checklist

Replace /api/v1/ with /api/v2/ in every call, and /api/systems/export/{name} with /api/v2/systems/{name}/export.
Change claude-design-kit to design-system-kit.
If you still use a design handoff key, create an API key and send it as Authorization: Bearer <key>. v2 never accepts a handoff key.
Update MCP prompts and scripts that call a tool by an older name to the new name.
If you call the prompt pack, pass agent=other when the agent building the round has no Artifact tool.
Watch your logs for a Sunset header on any response: that call still uses v1 or a handoff key.

One call before and after

# Before
curl https://brandpilot.dev/api/v1/designs/{id}/handoff \
  -H "Authorization: Bearer $BRANDPILOT_API_KEY"

# After
curl https://brandpilot.dev/api/v2/designs/{id}/handoff \
  -H "Authorization: Bearer $BRANDPILOT_API_KEY"

Every change is also listed in the changelog.