SudoMock
GET

List Mockups

Retrieve all your uploaded mockup templates with pagination, filtering, and sorting options.

GET/api/v1/mockups

Request

Headers

x-api-keystring

Your SudoMock API key starting with sm_. Required if not using Bearer token.

Authorizationstring

Bearer token (Supabase JWT). Format: "Bearer <token>". Required if not using x-api-key.

Authentication

Provide either x-api-key or Authorization: Bearer <token>. One of the two is required.

Query Parameters

limitinteger

Number of mockups to return. Min: 1, Max: 100, Default: 20

offsetinteger

Number of mockups to skip for pagination. Default: 0

namestring

Filter mockups by name (case-insensitive, partial match).

created_afterstring

Filter mockups created on or after this date (ISO 8601 format, inclusive).

created_beforestring

Filter mockups created on or before this date (ISO 8601 format, inclusive).

sortstring

Field to sort by: name, created_at, or updated_at. Default: created_at

orderstring

Sort order: asc or desc. Default: desc

Pagination

Use limit and offset to paginate through results. The response includes total to help calculate total pages.

Code Examples

List Mockups
bash
1# Basic list - first 20 mockups
2curl -X GET "https://api.sudomock.com/api/v1/mockups" \
3  -H "x-api-key: sm_your_api_key"
4

5# With pagination
6curl -X GET "https://api.sudomock.com/api/v1/mockups?limit=50&offset=20" \
7  -H "x-api-key: sm_your_api_key"
8

9# With filters and sorting
10curl -X GET "https://api.sudomock.com/api/v1/mockups?sort=name&order=asc&created_after=2025-01-01T00:00:00Z" \
11  -H "x-api-key: sm_your_api_key"

Response

Success Response

200OK
Response 200 OK
1{
2  "success": true,
3  "data": {
4    "mockups": [
5      {
6        "uuid": "abc123-def456-ghi789",
7        "name": "Product Mockup",
8        "thumbnail": "https://cdn.sudomock.com/abc123/thumbnails/thumb_720.jpg",
9        "width": 3000,
10        "height": 2000,
11        "smart_objects": [
12          {
13            "uuid": "so-uuid-001",
14            "name": "Product Image",
15            "layer_name": "Product Image",
16            "size": { "width": 3000, "height": 3000 },
17            "position": { "x": 100, "y": 100, "width": 800, "height": 600 },
18            "quad": null,
19            "blend_mode": "normal",
20            "print_area_presets": [
21              {
22                "uuid": "preset-uuid-001",
23                "name": "Default",
24                "thumbnails": [],
25                "size": { "width": 3000, "height": 3000 },
26                "position": { "x": 0, "y": 0, "width": 3000, "height": 3000 }
27              }
28            ]
29          }
30        ],
31        "text_layers": [],
32        "collections": [],
33        "thumbnails": [
34          { "width": 720, "url": "https://cdn.sudomock.com/abc123/thumbnails/thumb_720.jpg" },
35          { "width": 480, "url": "https://cdn.sudomock.com/abc123/thumbnails/thumb_480.jpg" },
36          { "width": 240, "url": "https://cdn.sudomock.com/abc123/thumbnails/thumb_240.jpg" }
37        ]
38      }
39    ],
40    "total": 156,
41    "limit": 20,
42    "offset": 0
43  }
44}

Response Fields

successbooleanRequired

Whether the request was successful. Always true for 200 responses.

data.mockupsarrayRequired

Array of mockup objects.

data.totalintegerRequired

Total number of mockups matching the query (before pagination).

data.limitintegerRequired

The limit that was applied.

data.offsetintegerRequired

The offset that was applied.

Mockup Object

uuidstringRequired

Unique identifier for the mockup.

namestringRequired

Name of the mockup template.

thumbnailstringRequired

URL to the mockup preview image (720px width). Empty string if no thumbnails are available.

widthinteger | null

Original PSD canvas width in pixels. Null if not yet processed.

heightinteger | null

Original PSD canvas height in pixels. Null if not yet processed.

smart_objectsarrayRequired

List of smart object layers in the mockup. See Smart Object fields below.

text_layersarrayRequired

Reserved for future use. Currently always an empty array.

collectionsarrayRequired

Reserved for future use. Currently always an empty array.

thumbnailsarrayRequired

Array of thumbnail objects at different sizes (720px, 480px, 240px). Each object has width (integer) and url (string) fields.

Smart Object Fields

uuidstringRequired

Unique identifier for the smart object.

namestringRequired

Display name of the smart object.

layer_namestring | null

Same as the name field. Included for backward compatibility.

sizeobjectRequired

Embedded (source) dimensions of the smart object. Contains width and height in pixels.

positionobjectRequired

Bounding box on the PSD canvas. Contains x, y, width, and height in pixels.

quadarray | null

4-point perspective transform coordinates (array of [x, y] pairs). Only populated for Scale tier users; null for Free and Pro tiers.

blend_modestring | null

Always "normal". Included for forward compatibility.

print_area_presetsarrayRequired

Array of print area presets. Currently contains a single "Default" preset matching the smart object size. Each preset has uuid, name, thumbnails, size, and position fields.

Geometry Data

The quad field (corner coordinates) is only included for Scale tier users. Free and Pro tier users will see quad: null in the response.

Error Responses

401Unauthorized
json
1{
2  "detail": "Invalid or missing API key",
3  "success": false
4}
429Too Many Requests

Returned when the API rate limit or concurrent request limit is exceeded. Check the Retry-After response header for how long to wait.

json
1{
2  "detail": "Rate limit exceeded. Try again in 30 seconds.",
3  "error": {
4    "type": "rate_limit_exceeded",
5    "code": "RATE_LIMIT_EXCEEDED",
6    "limit": 1000,
7    "remaining": 0,
8    "reset_seconds": 30,
9    "retry_after": 30,
10    "resource": "api"
11  }
12}
500Internal Server Error
json
1{
2  "detail": "Internal error while listing mockups"
3}

Pagination Example

Here's how to paginate through all your mockups:

Paginate Through All Mockups
1async function getAllMockups(apiKey) {
2  const allMockups = [];
3  const limit = 100;
4  let offset = 0;
5  let total = null;
6

7  do {
8    const response = await fetch(
9      `https://api.sudomock.com/api/v1/mockups?limit=${limit}&offset=${offset}`,
10      { headers: { "x-api-key": apiKey } }
11    );
12    
13    const data = await response.json();
14    allMockups.push(...data.data.mockups);
15    
16    total = data.data.total;
17    offset += limit;
18    
19  } while (offset < total);
20

21  return allMockups;
22}

Try It Live

GET/api/v1/mockups?limit=20&offset=0

List all your mockups with pagination.

Get your API key from the Dashboard

Best Practices

Performance Tips

  • Use limit=100 (max) for bulk operations to minimize API calls
  • Cache the total value and only refetch when adding/removing mockups
  • Store mockup UUIDs locally after initial sync to avoid repeated list calls
  • Use date filters (created_after) for incremental syncs

Common Issues

  • Empty results: Check if your API key has any uploaded mockups
  • Missing mockups: Ensure offset + limit doesn't exceed total
  • Slow response: Reduce limit or add filters for large collections

Related Endpoints

Upload PSD

Add new mockup templates

Get Mockup

Get full mockup details

Render Mockup

Generate mockup images

Upload PSDGet Mockup Detail
List Mockups Endpoint | SudoMock Docs