> ## 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 new artifact

> Creates a new artifact by cloning an existing one (typically the
currently active artifact). The new artifact becomes the active
artifact for the design and a new version entry is added to the
timeline.

Use this to create a safe working branch before writing files —
users can revert to the previous artifact if needed.




## OpenAPI

````yaml openapi-v3.yml post /v3/designs/{editorId}/artifacts
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/{editorId}/artifacts:
    post:
      tags:
        - Artifacts
      summary: Create a new artifact
      description: |
        Creates a new artifact by cloning an existing one (typically the
        currently active artifact). The new artifact becomes the active
        artifact for the design and a new version entry is added to the
        timeline.

        Use this to create a safe working branch before writing files —
        users can revert to the previous artifact if needed.
      operationId: createArtifactV3
      parameters:
        - $ref: '#/components/parameters/EditorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sourceArtifactId
                - name
              properties:
                sourceArtifactId:
                  type: string
                  description: >-
                    The artifact ID to clone from (usually the current active
                    artifact).
                name:
                  type: string
                  description: >-
                    A name for this artifact version, shown in the design
                    timeline.
                  example: Header tweaks
      responses:
        '200':
          description: New artifact created and set as active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    EditorId:
      name: editorId
      in: path
      required: true
      description: The design's editor ID.
      schema:
        type: string
        example: abc123
  schemas:
    ArtifactSummary:
      type: object
      properties:
        artifactId:
          type: string
        files:
          type: array
          items:
            type: string
    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'
    Forbidden:
      description: The caller does not have access to this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested design or artifact does not exist.
      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.

````