Skip to main content

Documentation Index

Fetch the complete documentation index at: https://magicpatterns.mintlify.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Magic Patterns API lets you create and iterate on designs programmatically — kicking off generations, polling status, reading and writing artifact files, and publishing changes — all from your own systems. v3 is the current API surface. It mirrors the Magic Patterns MCP server endpoint-for-endpoint, so the same key works for both REST and MCP. You don’t need to choose.
Already integrated against the legacy /v2/pattern endpoint? See the v2 reference. v2 is being deprecated and will be removed in a future release — plan to migrate to v3 when convenient.

​
Authentication

All v3 endpoints require an API key in the x-mp-api-key header.
1

Log in

Sign in (or create an account) at magicpatterns.com.
2

Create an API key

Open Settings → API Keys and click Create Key. Copy the key immediately — you can only see it once.
3

Send your first request

Use the key in the x-mp-api-key header on every request.
curl https://api.magicpatterns.com/api/v3/health \
  -H "x-mp-api-key: mp_live_..."
A 200 OK with {"status":"ok"} confirms your key is valid.

​
Billing

v3 usage draws from your normal Magic Patterns credit balance — the same credits the web app and MCP use. There is no separate API subscription.
  • Free-tier accounts get free monthly credits and can call v3 up to that limit.
  • Need more? Upgrade your plan or buy credit packs at Settings → Billing & Subscription.
  • When you run out, v3 calls that consume credits return 402 Payment Required. Read endpoints continue to work.

​
Quickstart: create a design

This kicks off generation in the background, then polls until the design is ready. 
# 1. Create the design — returns immediately with an editorId.
curl https://api.magicpatterns.com/api/v3/designs \
  -H "x-mp-api-key: mp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A landing page for a coffee shop"}'

# Response:
# { "editorId": "abc123", "editorUrl": "https://www.magicpatterns.com/c/abc123", ... }

# 2. Poll status until generation finishes. Wait at least 60 seconds between polls.
curl https://api.magicpatterns.com/api/v3/designs/abc123/status \
  -H "x-mp-api-key: mp_live_..."

# Response:
# { "isGenerating": false, "activeArtifactId": "...", "availableFiles": [...] }
Generation typically takes 2–10 minutes. Don’t poll more than once every 60 seconds.

​
Asynchronous endpoints

Two endpoints kick off long-running work and return immediately:
  • POST /v3/designs (when prompt is set)
  • POST /v3/designs/{editorId}/prompts
Both return a requestId (or editorId) right away. To know when the work is done, poll GET /v3/designs/{editorId}/status until isGenerating is false. There are no webhooks in v3 — polling is the only mechanism. We may add webhooks in a future release if customers ask.

​
Same key for MCP

The same API key authenticates the Magic Patterns MCP server. If you’ve installed MCP locally and have a key, you don’t need to do anything extra — just use the key with both transports.

​
Common errors

StatusMeaning
400Invalid input — check the request body and parameters.
401Missing or invalid x-mp-api-key.
402Out of credits. Top up at Settings → Billing.
403The key’s owner doesn’t have access to the requested design or artifact.
404The design or artifact doesn’t exist.
422Compilation failed on a publish call.
500Unexpected server error — logged on our side.
All error responses are application/json with a single error field: 
{ "error": "Insufficient credits. Please upgrade your plan or add credits." }

​
Rate limits

1000 generations per 10 hours per key. Contact us if you need a higher limit.

​
Next steps

Browse endpoints

Full API reference with request/response examples and a try-it widget.

MCP server

Use the same key with our Model Context Protocol server.