API documentation

All API requests require authentication using a Bearer token. To get your API key:

1. Create an account at MockupKit Dashboard
2. Navigate to the API Keys page
3. Create a new API Key and use the key as a Bearer token
4. Include it in the Authorization header of all requests

Endpoint

Description

Returns your templates. By default the response includes full smart_objects and color_fills. Use ?fields=summary for a lightweight catalogue that omits smart_objects.

Filter with any key from GET Filter Config (e.g. ?fields=summary&product_type=mugs). Multiple filters use AND logic. For full detail on one template, use GET Template by ID.

Query Parameters

Response Example (full)

Default response includes smart_objects and optional color_fills.

{
  "success": true,
  "templates": [
    {
      "template_id": "004bfee0-8243-46df-9d5a-41bd1b018942",
      "name": "Round Ceramic",
      "filename": "Round Ceramic 3.psd",
      "smart_objects": [
        {
          "width": 1067,
          "inner_canvas_width": 972,
          "layer_id": "smart_0",
          "inner_canvas_height": 973,
          "layer_name": "Design",
          "height": 1067
        }
      ],
      "file_size": "9.31 MB",
      "uploaded_at": "2025-09-19T15:16:14.463Z",
      "thumbnail_url": "thumbnail_url",
      "collections": []
    }
  ]
}

Response Example (summary catalogue)

With ?fields=summary and optional filter params. Omits smart_objects; includes color_fills when the template has PSD colour layers.

{
  "success": true,
  "count": 2,
  "fields": "summary",
  "applied_filters": {
    "product_type": "apparel"
  },
  "templates": [
    {
      "template_id": "b56e03e2-05e4-4847-bec9-941680dcd444",
      "name": "Letterman Jacket",
      "filename": "letterman-jacket.psd",
      "thumbnail_url": "https://.../thumbnail.png",
      "product_type": "apparel",
      "mockup_filters": {
        "product_type": "apparel",
        "garment_type": "jacket"
      },
      "color_fills": [
        {
          "layer_name": "Color",
          "color": { "r": 239, "g": 62, "b": 63, "hex": "#EF3E3F" }
        },
        {
          "layer_name": "Sleeve Color",
          "color": { "r": 239, "g": 62, "b": 63, "hex": "#EF3E3F" }
        }
      ],
      "collections": []
    }
  ]
}

Endpoint

Description

Returns filter taxonomy (group labels, option labels, custom groups, and exclusions) so you can build filter UIs without downloading every template. Use groups[].key as query param names on GET Templates.

Response Example

{
  "success": true,
  "groups": [
    {
      "key": "product_type",
      "label": "Product type",
      "options": [
        { "value": "apparel", "label": "Apparel" },
        { "value": "mugs", "label": "Mugs" },
        { "value": "framed-prints", "label": "Framed prints" }
      ]
    },
    {
      "key": "frame_type",
      "label": "Frame type",
      "options": [
        { "value": "dark-wood", "label": "Dark wood" },
        { "value": "dark-brown", "label": "Dark brown" }
      ]
    }
  ],
  "custom_groups": [],
  "exclusions": []
}

Endpoint

Description

Fetch one template with full detail for render setup. Looks up your own templates first, then the public mockup catalogue if not found. smart_objects lists every replaceable frame (up to 8). Texture, shadow, highlight, reflection, tag, overlay, and displacement smart objects stay in the scene and are not listed. Summary catalogue responses omit smart_objects, so load this endpoint before rendering a template that may have more than one frame. Slot names on one template are unique. Match artwork by layer_name, not by array position.

Path Parameters

Response Example

{
  "success": true,
  "template": {
    "template_id": "01773337-3a38-44d5-9486-9756b590a1de",
    "name": "12x12\" Dark Brown Frame with Mount",
    "filename": "12x12-dark-brown-frame-with-mount.psd",
    "description": null,
    "created_at": "2026-01-15T10:30:00.000Z",
    "uploaded_at": "2026-01-15T10:30:00.000Z",
    "file_size": "4.2 MB",
    "thumbnail_url": "https://.../thumbnail.png",
    "rotate_canvas": "yes",
    "is_public": false,
    "frame_type": "dark-brown",
    "size": "12x12",
    "product_type": "framed-prints",
    "mockup_filters": {
      "frame_type": "dark-brown",
      "product_type": "framed-prints",
      "size": "12x12"
    },
    "collections": [
      {
        "collection_id": "abc123...",
        "title": "12x12 Frames",
        "color": "blue"
      }
    ],
    "smart_objects": [
      {
        "layer_name": "Rectangle 1",
        "layer_id": "smart_0",
        "width": 1500,
        "height": 1500,
        "inner_canvas_width": 1545,
        "inner_canvas_height": 1545,
        "preview": {
          "meta_version": 1,
          "document_width": 2000,
          "document_height": 2000,
          "bounds": { "left": 228, "top": 228, "right": 1773, "bottom": 1773 },
          "appearance": {
            "opacity": 1,
            "fill_opacity": 1,
            "blend_mode": "multiply",
            "visible": true
          },
          "masks": {
            "has_layer_mask": true,
            "clip_mask_url": "https://.../clip-mask.png"
          },
          "transform": {
            "type": "identity",
            "corners": [
              { "x": 228, "y": 228 },
              { "x": 1773, "y": 228 },
              { "x": 1773, "y": 1773 },
              { "x": 228, "y": 1773 }
            ]
          }
        }
      }
    ],
    "color_fills": [
      {
        "layer_name": "Color",
        "layer_path": "Group/Color",
        "color": { "r": 239, "g": 62, "b": 63, "hex": "#EF3E3F" },
        "fill_mask_url": "https://.../fill-masks/color.png",
        "masks": [
          { "id": "Color-layer-raster", "kind": "layer_raster", "url": "https://..." }
        ],
        "blend_mode": "normal",
        "parent_group": { "name": "Group", "blend_mode": "normal" }
      },
      {
        "layer_name": "Sleeve Color",
        "color": { "r": 239, "g": 62, "b": 63, "hex": "#EF3E3F" },
        "fill_mask_url": "https://.../fill-masks/sleeve-color.png"
      }
    ]
  }
}

Error Response

{
  "success": false,
  "error": "Template not found"
}

HTTP 404

Colour Fills

Templates with Photoshop solid colour fill layers include a color_fills array in the response above. See the dedicated Colour Fills section for field reference and render override examples.

Endpoint

Description

Retrieves a list of all template collections. Collections group related templates together (e.g., "Gift Wrap", "T-Shirt Mockups", "Mug Mockups"). Each collection includes the collection ID, title, description, color, template count, array of template IDs, and creation/update timestamps.

Response Example

{
  "success": true,
  "collections": [
    {
      "collection_id": "36209421-29a2-4b1e-9d23-0af0fe981ed2",
      "title": "Gift Wrap",
      "description": "Bring your patterns to life with gift wrap mockups that look ready to unwrap",
      "color": "blue",
      "template_count": 14,
      "template_ids": [
        "template_id_1",
        "template_id_2",
        "template_id_3"
      ],
      "created_at": "2025-09-21T17:48:23.326Z",
      "updated_at": "2025-09-21T18:48:20.161Z"
    }
  ]
}

Endpoint

Description

Fetch all templates in a collection with full template metadata, returned in the collection's saved order. Supports both user-owned templates and public templates added to the collection.

Path Parameters

Response Example

{
  "success": true,
  "collection_id": "00389179-bbb8-44f0-9828-7b1cb5a040a2",
  "title": "8x8 Dark Wood Frame",
  "description": "",
  "color": "blue",
  "count": 1,
  "templates": [
    {
      "template_id": "8f10f325-6f8b-4543-8b9f-70ddc3c3ae1f",
      "name": "8x8\" Dark Wood Frame",
      "filename": "8x8-dark-wood-frame.psd",
      "thumbnail_url": "https://.../thumbnail.png",
      "rotate_canvas": "yes",
      "frame_type": "dark-wood",
      "product_type": "framed-prints",
      "smart_objects": [
        {
          "layer_name": "Rectangle 1",
          "layer_id": "smart_0",
          "width": 1501,
          "height": 1497,
          "preview": {
            "meta_version": 1,
            "document_width": 2000,
            "document_height": 2000,
            "appearance": { "blend_mode": "multiply" },
            "transform": {
              "type": "identity",
              "corners": [
                { "x": 228, "y": 228 },
                { "x": 1773, "y": 228 },
                { "x": 1773, "y": 1773 },
                { "x": 228, "y": 1773 }
              ]
            }
          }
        }
      ],
      "color_fills": [
        {
          "layer_name": "Frame Color",
          "color": { "hex": "#3D2914" },
          "fill_mask_url": "https://.../frame-color.png"
        }
      ]
    }
  ]
}

Empty collections return templates: [] and count: 0 with HTTP 200.

Error Response

{
  "success": false,
  "error": "Collection not found"
}

HTTP 404

Endpoint

Description

Generates one finished mockup from a template. A template with one smart object takes artwork_url. A template with more than one smart object takes artworks and omits artwork_url. The finished image still costs 1 credit, however many frames it contains. See Multiple smart objects.

Request Body

Request Example

{
  "template_id": "004bfee0-8243-46df-9d5a-41bd1b018942",
  "artwork_url": "https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=800",
  "output_format": "jpg",
  "color_fills": {
    "Shirt Color": "#FF7300"
  }
}

Response Example

{
  "success": true,
  "batch": true,
  "total_templates": 1,
  "successful_renders": 1,
  "failed_renders": 0,
  "total_processing_time": "2787ms",
  "collection_title": null,
  "render_credits": "0/99999999",
  "usage_info": {
    "current_usage": 0,
    "limit": 99999999,
    "plan": "professional",
    "remaining": 99999999
  },
  "results": [
    {
      "success": true,
      "job_id": "06a95863-bd5e-4e08-9aae-7d228d2ca483",
      "template_id": "004bfee0-8243-46df-9d5a-41bd1b018942",
      "status": "completed",
      "render_url": "https://render.mockupkit.app/eu-west-2:1c2102c9-e87d-ce02-2bdb-1f7e6f06276a/06a95863-bd5e-4e08-9aae-7d228d2ca483.jpg",
      "processing_time": "2770ms"
    }
  ]
}

Description

Some templates accept more than one artwork in a single render. A framed set, diptych, or gallery wall can place a different image in each frame and return one finished mockup. Templates with one smart object are unchanged: keep sending artwork_url. A finished mockup still costs 1 credit, however many images it contains.

smart_objects on a full template is the list of images you can replace. Each entry’s layer_name is the name you send with that image. inner_canvas_width and inner_canvas_height are the recommended size for that frame. Templates already in your account keep a single slot until that PSD is processed again.

Request Example

{
  "template_id": "8f10f325-6f8b-4543-8b9f-70ddc3c3ae1f",
  "output_format": "jpg",
  "color_fills": {
    "Frame Color": "#1A1A1A"
  },
  "artworks": [
    {
      "layer_name": "Left",
      "artwork_url": "https://your-cdn.com/left.jpg"
    },
    {
      "layer_name": "Right",
      "artwork_url": "https://your-cdn.com/right.jpg"
    }
  ]
}

One-slot templates can still use artwork_url. They can also take a single artworks entry. color_fills still applies to the whole document.

Rules

• Every slot on that template must be present.
• layer_name values must match the template. Unknown or duplicate names return 400.
• A single artwork_url on a multi-slot template returns 400. The first frame is not filled on its own.
• Images larger than 4096px on the long edge are scaled down before they are placed. Send JPG, PNG, or SVG, up to 10MB per image.

Error Response

{
  "success": false,
  "error": "This template has 2 smart objects (Left, Right). Send artworks[] with one image per layer_name."
}

Missing a slot returns Missing artwork for smart object "Right". An unknown name returns Unknown smart object "Center". HTTP 400.

POST /v1/render-upload

Same body as /v1/render, with artwork_key from POST /v1/upload-url in place of each URL. Upload each image with its own presigned URL, then send the keys together. A single artwork_key on a multi-slot template returns 400.

{
  "template_id": "8f10f325-6f8b-4543-8b9f-70ddc3c3ae1f",
  "output_format": "png",
  "artworks": [
    { "layer_name": "Left", "artwork_key": "user-id/left.png" },
    { "layer_name": "Right", "artwork_key": "user-id/right.png" }
  ]
}

Multipart render

POST /v1/public-render and POST /v1/user-render accept multipart/form-data. One smart object still sends one file and smart_layer_name. More than one smart object repeats the file field once per slot and sends layer_names as a JSON array in the same order. You can send a repeated layer_name field in the same order as the files instead of layer_names. The file count must match the slot count.

curl -X POST https://api.mockupkit.app/v1/user-render \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "template_id=8f10f325-6f8b-4543-8b9f-70ddc3c3ae1f" \
  -F "output_format=png" \
  -F 'layer_names=["Left","Right"]' \
  -F "file=@left.jpg" \
  -F "file=@right.jpg"

Upload limits for new PSDs

When you upload a PSD, replaceable smart objects are stored up to a maximum of 8. A file with more than 8 replaceable smart objects is rejected with too_many_smart_objects. Two slots with the same layer name are rejected with duplicate_smart_object_names. A PSD with no replaceable smart object is rejected with no_smart_objects.

Endpoint

Description

Generates mockups for multiple one-slot templates using a single artwork. Perfect for creating variations of your design across different product types or angles. If any template in the request has more than one smart object, send artworks instead of artwork_url. Rendering many different artworks across many multi-slot templates in one batch is not supported — call POST /v1/render once per multi-slot template.

Request Body

Request Example

{
  "template_ids": [
    "00028c53-9ccb-4044-8d72-6b196e246c01",
    "014c4fcb-be09-4904-903d-2438b70ccedb"
  ],
  "artwork_url": "https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=800",
  "output_format": "jpg",
  "color_fills": {
    "Shirt Color": "#FF7300"
  }
}

Endpoint

Description

Generates mockups for the one-slot templates in a collection using a single artwork. This is ideal for product line presentations where you want to showcase your design across an entire collection. A multi-slot template in that collection needs artworks with an image for each of its layer_name values. A one-slot template in the same request uses the artwork whose layer_name matches its slot, or the only entry when artworks contains a single image.

Request Body

Request Example

{
  "collection_id": "7b6d0216-9add-4c5a-8ee9-f582066137bd",
  "artwork_url": "https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=800",
  "output_format": "jpg",
  "color_fills": {
    "Shirt Color": "#FF7300"
  }
}