Skip to main content
POST
/
v3
/
designs
Create a design
curl --request POST \
  --url https://api.magicpatterns.com/api/v3/designs \
  --header 'Content-Type: application/json' \
  --header 'x-mp-api-key: <api-key>' \
  --data '
{
  "name": "Onboarding flow",
  "prompt": "A login page with social sign-in.",
  "imageUrls": [
    "<string>"
  ],
  "designSystemId": "<string>",
  "designSystem": "<string>",
  "templateId": "<string>"
}
'
{
  "editorId": "abc123",
  "editorUrl": "https://www.magicpatterns.com/c/abc123",
  "previewUrl": "https://project-onboarding-flow.magicpatterns.app",
  "activeArtifactId": "<string>",
  "availableFiles": [
    "<string>"
  ]
}

Authorizations

​
x-mp-api-key
string
header
required

Magic Patterns API key. The same key authenticates v3 REST and the MCP server. Create one at https://www.magicpatterns.com/settings/api-keys.

Body

application/json
​
name
string

Optional name for the design. Defaults to "Untitled".

Example:

"Onboarding flow"

​
prompt
string

Optional natural-language prompt. If supplied, AI generation runs in the background and the caller must poll GET /v3/designs/{editorId}/status. If omitted, a blank design with scaffold files is created instantly.

Example:

"A login page with social sign-in."

​
imageUrls
string<uri>[]

Optional image URLs to use as visual references (only used with prompt).

​
designSystemId
string

Optional ID of the design system to use. Discover IDs via GET /v3/design-systems.

​
designSystem
string

Optional design system name (e.g. "Shadcn"). Resolved case-insensitively. designSystemId takes precedence if both are provided.

​
templateId
string

Optional editor ID of an existing design to use as a template. The design is forked first, then any prompt is applied to the fork.

Response

Design created. If generation is in flight, poll status.

​
editorId
string
Example:

"abc123"

​
editorUrl
string<uri>
Example:

"https://www.magicpatterns.com/c/abc123"

​
previewUrl
string<uri> | null

Live preview URL. Only populated once the first artifact has been compiled.

Example:

"https://project-onboarding-flow.magicpatterns.app"

​
activeArtifactId
string | null

The artifact created at design-creation time. Null until the first artifact is ready.

​
availableFiles
string[]

File names in the active artifact. Empty while generation is still running.