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

# Send a prompt

> Sends a natural-language prompt to update an existing design. Returns
immediately with a `requestId`; the AI generation runs in the
background.

Poll `GET /v3/designs/{editorId}/status` until `isGenerating` is
`false`. Generation typically takes 2–10 minutes; do not poll more
than once every 60 seconds.

Before calling, check `GET /v3/designs/{editorId}/status` to confirm
the design isn't already generating.

Bills credits from the authenticated user's normal credit balance.




## OpenAPI

````yaml openapi-v3.yml post /v3/designs/{editorId}/prompts
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}/prompts:
    post:
      tags:
        - Designs
      summary: Send a prompt
      description: |
        Sends a natural-language prompt to update an existing design. Returns
        immediately with a `requestId`; the AI generation runs in the
        background.

        Poll `GET /v3/designs/{editorId}/status` until `isGenerating` is
        `false`. Generation typically takes 2–10 minutes; do not poll more
        than once every 60 seconds.

        Before calling, check `GET /v3/designs/{editorId}/status` to confirm
        the design isn't already generating.

        Bills credits from the authenticated user's normal credit balance.
      operationId: sendPromptV3
      parameters:
        - $ref: '#/components/parameters/EditorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  description: Natural language description of the change to make.
                  example: Add a footer with three columns of links.
      responses:
        '200':
          description: Prompt accepted. Generation runs in the background.
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    description: Opaque identifier for this generation run.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '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
  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'
    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'
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: You do not have access to this resource.
  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.

````