> ## Documentation Index
> Fetch the complete documentation index at: https://magicpatterns.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Programmatic access to Magic Patterns with the v3 API

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](/documentation/features/mcp-server/overview) endpoint-for-endpoint, so the same key works for both REST and MCP. You don't need to choose.

<Note>
  Already integrated against the legacy `/v2/pattern` endpoint? See the [v2 reference](/documentation/api/getting-started). v2 is being deprecated and will be removed in a future release — plan to migrate to v3 when convenient.
</Note>

## Authentication

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

<Steps>
  <Step title="Log in">
    Sign in (or create an account) at [magicpatterns.com](https://www.magicpatterns.com/).
  </Step>

  <Step title="Create an API key">
    Open [Settings → API Keys](https://www.magicpatterns.com/settings/api-keys) and click **Create Key**. Copy the key immediately — you can only see it once.
  </Step>

  <Step title="Send your first request">
    Use the key in the `x-mp-api-key` header on every request.
  </Step>
</Steps>

```bash theme={null}
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](https://www.magicpatterns.com/settings/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.

```bash theme={null}
# 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](/documentation/features/mcp-server/overview). 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

| Status | Meaning                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | Invalid input — check the request body and parameters.                                               |
| `401`  | Missing or invalid `x-mp-api-key`.                                                                   |
| `402`  | Out of credits. Top up at [Settings → Billing](https://www.magicpatterns.com/settings/subscription). |
| `403`  | The key's owner doesn't have access to the requested design or artifact.                             |
| `404`  | The design or artifact doesn't exist.                                                                |
| `422`  | Compilation failed on a `publish` call.                                                              |
| `500`  | Unexpected server error — logged on our side.                                                        |

All error responses are `application/json` with a single `error` field:

```json theme={null}
{ "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

<CardGroup cols={2}>
  <Card title="Browse endpoints" icon="code" href="/api/health">
    Full API reference with request/response examples and a try-it widget.
  </Card>

  <Card title="MCP server" icon="plug" href="/documentation/features/mcp-server/overview">
    Use the same key with our Model Context Protocol server.
  </Card>
</CardGroup>