API documentation

MockupKit's Mockup API lets developers generate photorealistic product images programmatically via a REST API.

This reference covers authentication, template and collection endpoints, filter config, colour fill metadata, render requests, and response formats for integrating mockup generation into your application.

Quick Navigation

Authentication

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

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

Example Request Header

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Security Best Practices

Never expose your API key in client-side code or public repositories
Use environment variables to store your API key
Rotate your API keys regularly
Monitor your API usage in the dashboard

Base URL

https://api.mockupkit.app

All API endpoints are prefixed with /v1

Method	Path	Description
GET	/v1/collections	List collections with template IDs
GET	/v1/collections/:collectionId/templates	Collection templates with full template metadata
GET	/v1/filter-config	Filter taxonomy for building catalogue UIs
GET	/v1/templates	All templates (full by default; use `?fields=summary` for catalogue)
GET	/v1/templates/:templateId	One template with smart objects and colour fills
POST	/v1/render	Single render with `template_id`
POST	/v1/render	Batch render with `template_ids[]`
POST	/v1/render	Collection render with `collection_id`

Recommended Discovery Flow

For catalogue UIs with filters and colour pickers, fetch metadata in three steps rather than downloading every template with full smart_objects payloads upfront.

GET /v1/filter-config: build filter dropdowns from groups[].options.
GET /v1/templates?fields=summary&…: list thumbnails, names, mockup_filters, and optional color_fills defaults (no smart_objects).
GET /v1/templates/:templateId: when the user selects a template, load full detail including color_fills for render setup.

# Step 1 - filter taxonomy
GET /v1/filter-config

# Step 2 - filtered catalogue
GET /v1/templates?fields=summary&product_type=apparel

# Step 3 - full template detail
GET /v1/templates/b56e03e2-05e4-4847-bec9-941680dcd444

# Step 4 - render with colour overrides
POST /v1/render
{
  "template_id": "b56e03e2-05e4-4847-bec9-941680dcd444",
  "artwork_url": "https://your-cdn.com/design.png",
  "output_format": "jpg",
  "color_fills": { "Sleeve Color": "#2563EB" }
}

GET

Get Templates

Endpoint

GET https://api.mockupkit.app/v1/templates

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

Parameter	Values	Description
fields	summary	Omit smart_objects for a lightweight catalogue payload
{filter_key}	slug	Filter by mockup filter value (e.g. product_type, frame_type)

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": []
    }
  ]
}

GET

Get Filter Config

Endpoint

GET https://api.mockupkit.app/v1/filter-config

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": []
}

GET

Get Template by ID

Endpoint

GET https://api.mockupkit.app/v1/templates/:templateId

Description

Fetch one template with full detail for render setup. Looks up your own templates first, then the public mockup catalogue if not found. Returns smart object metadata and color_fills when the PSD includes solid colour layers.

Path Parameters

Parameter	Type	Description
templateId	string (UUID)	The template ID to fetch

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.

Colour Fills

During PSD optimisation, solid colour fill layers are exported as color_fills[] on template endpoints. Each entry includes the default hex from the PSD and layer metadata. At render time, pass a flat map of layer_name → #RRGGBB. Mask URLs are not required in the render request.

Field	Type	Description
layer_name	string	PSD layer name; use as override key and colour picker label (case-insensitive at render)
layer_path	string	Optional nested path within the PSD layer stack
color.hex	string	Default colour from the PSD (also includes r, g, b)
fill_mask_url	string (URL)	Optional mask asset exported with the template (not used by POST /v1/render)
masks[]	array	Additional raster masks (kind, url) when multiple masks apply
blend_mode	string	PSD blend mode for the fill layer

Template response example

"color_fills": [
  {
    "layer_name": "Color",
    "layer_path": "Garment/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"
  },
  {
    "layer_name": "Sleeve Color",
    "color": { "hex": "#EF3E3F" },
    "fill_mask_url": "https://.../fill-masks/sleeve-color.png"
  }
]

Render override (POST /v1/render)

Optional color_fills object on single, batch, and collection render requests. Keys match layer_name; values are hex strings only.

{
  "template_id": "b56e03e2-05e4-4847-bec9-941680dcd444",
  "artwork_url": "https://your-cdn.com/design.png",
  "output_format": "jpg",
  "color_fills": {
    "Sleeve Color": "#2563EB",
    "Collar Color": "#111827"
  }
}

GET

Get Collections

Endpoint

GET https://api.mockupkit.app/v1/collections

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"
    }
  ]
}

GET

Get Collection Templates

Endpoint

GET https://api.mockupkit.app/v1/collections/:collectionId/templates

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

Parameter	Type	Description
collectionId	string (UUID)	The collection ID to fetch templates for

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

POST

Single Template Render

Endpoint

POST https://api.mockupkit.app/v1/render

Description

Generates a mockup by rendering a single template with your artwork. Returns the rendered mockup URL and processing information.

Request Body

Parameter	Type	Required	Description
template_id	string	Yes	Unique identifier of the template
artwork_url	string (URL)	Yes	Public URL of the artwork image to use
output_format	string	Yes	Output format: `"jpg"` or `"png"`
color_fills	object	No	Map of `layer_name → #RRGGBB` to override PSD solid fill layers. See Colour Fills.

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"
    }
  ]
}

POST

Batch Template Render

Endpoint

POST https://api.mockupkit.app/v1/render

Description

Generates mockups for multiple templates using a single artwork. Perfect for creating variations of your design across different product types or angles.

Request Body

Parameter	Type	Required	Description
template_ids	string[]	Yes	Array of template IDs to render
artwork_url	string (URL)	Yes	Public URL of the artwork image
output_format	string	Yes	Output format: `"jpg"` or `"png"`
color_fills	object	No	Same colour overrides applied to every template in the batch. See Colour Fills.

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"
  }
}

Batch Processing

The response will contain a results array with one entry per template. All renders are processed in parallel for optimal performance.

POST

Collection Render

Endpoint

POST https://api.mockupkit.app/v1/render

Description

Generates mockups for all templates within a collection using a single artwork. This is ideal for product line presentations where you want to showcase your design across an entire collection.

Request Body

Parameter	Type	Required	Description
collection_id	string	Yes	Unique identifier of the collection
artwork_url	string (URL)	Yes	Public URL of the artwork image
output_format	string	Yes	Output format: `"jpg"` or `"png"`
color_fills	object	No	Colour overrides applied to all templates in the collection. See Colour Fills.

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"
  }
}

Use Case

Perfect for generating product line mockups. For example, render your logo design across all t-shirt styles in the "T-Shirt Mockups" collection with a single API call.

Response Fields

Common Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
batch	boolean	Indicates if this was a batch operation
total_templates	number	Total number of templates processed
successful_renders	number	Number of successfully rendered mockups
failed_renders	number	Number of failed renders
total_processing_time	string	Total time taken to process all renders
render_credits	string	Current usage and limit in format "used/total"
results	array	Array of render results, each containing job_id, template_id, status, render_url, and processing_time
usage_info	object	Information about current plan usage including current_usage, limit, plan, and remaining credits

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OK - Request successful
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "error": "Error message describing what went wrong",
  "details": "Additional error details"
}

Rate Limits & Usage

API usage is based on your subscription plan. Each successful render consumes one credit from your plan's limit.

Usage Information

The API response includes usage_info showing:

current_usage - Credits used in current billing period
limit - Total credits available on your plan
plan - Your current subscription plan
remaining - Credits remaining in current period

Ready to get started?

Create your account and start generating professional mockups in minutes.

Create free account Need help? Contact us