> ## 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.

# Create a design

> Creates a new Magic Patterns design.

Behavior depends on the request:
- **With `prompt`**: kicks off AI generation in the background. The
  response returns immediately with `editorId`; poll
  `GET /v3/designs/{editorId}/status` until `isGenerating` is `false`.
  Generation typically takes 2–10 minutes.
- **Without `prompt`**: creates a blank design with scaffold files
  (App.tsx, index.tsx, index.css, tailwind.config.js) and returns
  immediately.
- **With `templateId`**: forks an existing design first, then optionally
  applies the prompt to the fork.

Generation calls bill credits from the authenticated user's normal
credit balance.




## OpenAPI

````yaml openapi-v3.yml post /v3/designs
openapi: 3.0.3
info:
  title: Magic Patterns API (v3)
  version: 3.0.0
  description: |
    The Magic Patterns API v3 provides programmatic access to design generation,
    iteration, and code-level editing. v3 mirrors the surface of the Magic
    Patterns MCP server — a single key authenticates both transports.

    v3 bills against your normal Magic Patterns credit balance. There is no
    separate API subscription. Free tier users can call v3 up to their credit
    limit, identical to web and MCP usage.

    For the legacy v2 single-shot creation endpoint (separate $99/mo plan),
    see the v2 reference.
servers:
  - url: https://api.magicpatterns.com/api
security:
  - ApiKeyAuth: []
tags:
  - name: Health
  - name: Design Systems
  - name: Designs
  - name: Artifacts
paths:
  /v3/designs:
    post:
      tags:
        - Designs
      summary: Create a design
      description: |
        Creates a new Magic Patterns design.

        Behavior depends on the request:
        - **With `prompt`**: kicks off AI generation in the background. The
          response returns immediately with `editorId`; poll
          `GET /v3/designs/{editorId}/status` until `isGenerating` is `false`.
          Generation typically takes 2–10 minutes.
        - **Without `prompt`**: creates a blank design with scaffold files
          (App.tsx, index.tsx, index.css, tailwind.config.js) and returns
          immediately.
        - **With `templateId`**: forks an existing design first, then optionally
          applies the prompt to the fork.

        Generation calls bill credits from the authenticated user's normal
        credit balance.
      operationId: createDesignV3
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDesignRequest'
      responses:
        '200':
          description: Design created. If generation is in flight, poll status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDesignResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateDesignRequest:
      type: object
      properties:
        name:
          type: string
          description: Optional name for the design. Defaults to "Untitled".
          example: Onboarding flow
        prompt:
          type: string
          description: |
            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:
          type: array
          description: >-
            Optional image URLs to use as visual references (only used with
            `prompt`).
          items:
            type: string
            format: uri
        designSystemId:
          type: string
          description: >-
            Optional ID of the design system to use. Discover IDs via `GET
            /v3/design-systems`.
        designSystem:
          type: string
          description: >-
            Optional design system name (e.g. "Shadcn"). Resolved
            case-insensitively. `designSystemId` takes precedence if both are
            provided.
        templateId:
          type: string
          description: >-
            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.
    CreateDesignResponse:
      type: object
      properties:
        editorId:
          type: string
          example: abc123
        editorUrl:
          type: string
          format: uri
          example: https://www.magicpatterns.com/c/abc123
        previewUrl:
          type: string
          format: uri
          nullable: true
          description: >-
            Live preview URL. Only populated once the first artifact has been
            compiled.
          example: https://project-onboarding-flow.magicpatterns.app
        activeArtifactId:
          type: string
          nullable: true
          description: >-
            The artifact created at design-creation time. Null until the first
            artifact is ready.
        availableFiles:
          type: array
          items:
            type: string
          description: >-
            File names in the active artifact. Empty while generation is still
            running.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: You do not have access to this resource.
  responses:
    BadRequest:
      description: Invalid or missing required input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientCredits:
      description: The authenticated user has run out of credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-mp-api-key
      description: >
        Magic Patterns API key. The same key authenticates v3 REST and the

        MCP server. Create one at
        https://www.magicpatterns.com/settings/api-keys.

````