# SudoMock -- Complete API & Platform Documentation

> SudoMock is a mockup automation infrastructure that reduces PSD processing from Adobe's $0.15/request to as low as $0.002 (Scale tier, high volume) -- built for Print on Demand automation at scale. Full Photoshop blend mode support, unlimited layers, professional-grade rendering, native Shopify and WooCommerce integrations, and a white-label customer-facing customization studio.

## Quick Summary

SudoMock processes Photoshop (PSD) files programmatically via REST API, enabling automated mockup generation at scale. Upload your PSD template once, then render unlimited variations by swapping Smart Object contents. Built with a Photoshop-accurate rendering engine supporting all 29 blend modes. SudoMock also offers native e-commerce integrations (Shopify App, WooCommerce Plugin) and an embeddable customer-facing customization studio for storefronts.

### Key Metrics
- **2,000,000,000+** renders processed
- **75x** cost-efficiency vs competitors
- **99.9%** uptime
- **Unlimited** dashboard usage on all plans

---

## Authentication

All API requests require an API key in the `x-api-key` header.

### API Key Format
API keys use the `sm_` prefix followed by 64 hex characters:
```
sm_a1b2c3d4e5f6...  (67 characters total)
```

### How to Authenticate
```http
x-api-key: sm_your_api_key_here
```

### Getting an API Key
1. Sign up at https://sudomock.com/register
2. Go to Dashboard > API Keys
3. Click "Create API Key"
4. Copy the key immediately (it is only shown once)

### Base URL
```
https://api.sudomock.com
```

All endpoints are prefixed with `/api/v1/`.

---

## API Endpoints -- Complete Reference

### 1. POST /api/v1/psd/upload

Upload and process a PSD file. Extracts layers, smart objects, and generates thumbnails.

**Auth:** x-api-key header

**Request Body:**
```json
{
  "psd_file_url": "https://your-storage.com/mockup.psd",
  "psd_name": "T-Shirt Front"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| psd_file_url | string | Yes | URL to the PSD file (HTTP/HTTPS). Max 300MB, 120s download timeout. |
| psd_name | string | No | Name for the mockup template. Auto-generated from filename if omitted. Max 255 chars. |

**Response (200):**
```json
{
  "success": true,
  "data": {
    "uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
    "name": "T-Shirt Front",
    "thumbnail": "https://cdn.sudomock.com/.../thumb_720.webp",
    "width": 4000,
    "height": 5000,
    "smart_objects": [
      {
        "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
        "name": "Chest Design",
        "size": { "width": 2000, "height": 2400 },
        "position": { "x": 500, "y": 300, "width": 1200, "height": 1500 },
        "print_area_presets": [
          {
            "uuid": "preset-uuid",
            "name": "Default",
            "thumbnails": [],
            "size": { "width": 2000, "height": 2400 },
            "position": { "x": 0, "y": 0, "width": 2000, "height": 2400 }
          }
        ],
        "layer_name": "Smart Object 1",
        "quad": null,
        "blend_mode": "normal"
      }
    ],
    "text_layers": [],
    "collections": [],
    "thumbnails": [
      { "width": 720, "url": "https://cdn.sudomock.com/.../thumb_720.webp" },
      { "width": 480, "url": "https://cdn.sudomock.com/.../thumb_480.webp" },
      { "width": 240, "url": "https://cdn.sudomock.com/.../thumb_240.webp" }
    ]
  },
  "message": ""
}
```

**Error Responses:**
- 400: PSD download failed, parse error, no smart objects found, or PSD file too large (exceeds 300MB)
- 401: Invalid or missing API key
- 429: Rate limit or concurrent upload limit exceeded
- 500: Internal server error

**Notes:**
- The `quad` field (4-point perspective coordinates) is only populated for Scale tier plans.
- `text_layers` and `collections` are reserved for future use (always empty).
- Each smart object's `size` represents the embedded content dimensions (the area your artwork fills).
- Each smart object's `position` represents the bounding box on the PSD canvas.

---

### 2. POST /api/v1/renders

Render a mockup by compositing user-provided images into smart object layers.

**Auth:** x-api-key header
**Credits:** 1 credit per render

**Request Body:**
```json
{
  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
  "smart_objects": [
    {
      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
      "asset": {
        "url": "https://your-cdn.com/design.png",
        "fit": "cover",
        "rotate": 0,
        "flip_horizontal": false,
        "flip_vertical": false,
        "size": { "width": 800, "height": 600 },
        "position": { "top": 10, "left": 20 }
      },
      "color": {
        "hex": "#FF5733",
        "blending_mode": "multiply"
      },
      "adjustment_layers": {
        "brightness": 0,
        "contrast": 0,
        "opacity": 100,
        "saturation": 0,
        "vibrance": 0,
        "blur": 0
      }
    }
  ],
  "export_options": {
    "image_format": "webp",
    "image_size": 1920,
    "quality": 95
  },
  "export_label": "my-custom-filename"
}
```

#### Request Fields

**Top-Level Fields:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| mockup_uuid | string (UUID) | Yes | UUID of the mockup to render (from upload or list response) |
| smart_objects | array | Yes | List of smart objects with assets (min 1) |
| export_options | object | No | Export configuration. Defaults: webp, 1920px, quality 95 |
| export_label | string | No | Custom filename prefix for the output. Max 100 chars. |

**smart_objects[].asset Fields:**

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| url | string | Conditional | - | URL to the image (HTTP/HTTPS or data: URL). Either `url` or `base64` required. |
| base64 | string | Conditional | - | Raw base64-encoded image (no data: prefix) (RECOMMENDED - 50-500ms faster than URL). Either `url` or `base64` required. |
| content_type | string | No | image/png | MIME type when using base64. Defaults to image/png if omitted. Supported: image/png, image/jpeg, image/webp, image/gif |
| fit | enum | No | "fill" | How to fit artwork: `fill` (stretch), `contain` (fit inside), `cover` (fill and crop) |
| rotate | integer | No | 0 | Rotation in degrees (-360 to 360) |
| flip_horizontal | boolean | No | false | Mirror artwork horizontally |
| flip_vertical | boolean | No | false | Mirror artwork vertically |
| size | object | No | null | Custom size override: `{ "width": int, "height": int }` |
| position | object | No | null | Custom position override: `{ "top": int, "left": int }` |

**smart_objects[].color Fields (optional):**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| hex | string | Yes | Hex color code (e.g., "#FF5733"). Pattern: ^#[0-9A-Fa-f]{6}$ |
| blending_mode | string | No | Blend mode for color overlay. Default: "normal". All 29 Photoshop blend modes supported. |

**Important:** Each smart object must include either `asset` or `color` (or both). Image source priority: base64 > url.

**smart_objects[].adjustment_layers Fields (optional):**

| Field | Type | Range | Default | Description |
|-------|------|-------|---------|-------------|
| brightness | integer | -150 to 150 | 0 | Brightness adjustment |
| contrast | integer | -100 to 100 | 0 | Contrast adjustment |
| opacity | integer | 0 to 100 | 100 | Artwork opacity (0=transparent, 100=opaque) |
| saturation | integer | -100 to 100 | 0 | Saturation (-100=grayscale) |
| vibrance | integer | -100 to 100 | 0 | Vibrance (preserves skin tones) |
| blur | integer | 0 to 100 | 0 | Gaussian blur amount |

**export_options Fields:**

| Field | Type | Range | Default | Description |
|-------|------|-------|---------|-------------|
| image_format | enum | png, jpg, webp | "webp" | Output format. WebP is 30-70% smaller (recommended). |
| image_size | integer | 100-10000 | 1920 | Output width in pixels. Height auto-calculated from PSD aspect ratio. |
| quality | integer | 1-100 | 95 | Compression quality for JPG/WebP. Ignored for PNG (always lossless). |

**Response (200):**
```json
{
  "success": true,
  "data": {
    "print_files": [
      {
        "export_path": "https://cdn.sudomock.com/renders/abc123/render_1711234567890.webp",
        "smart_object_uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9"
      }
    ]
  }
}
```

**Error Responses:**
- 400: Invalid request (bad UUID, missing asset, invalid smart object UUID)
- 401: Invalid or missing API key
- 402: Insufficient credits
- 404: Mockup not found
- 429: Rate limit or concurrent render limit exceeded
- 500: Internal server error (safe to retry)
- 502: Upstream image source error (cannot download user's image)

**Notes:**
- Rendered images are uploaded to CDN asynchronously. The URL is returned immediately.
- Standard renders are stored for 7 days. Custom domain users get permanent storage.
- `base64` input is recommended over `url` for best performance (50-500ms faster).

---

### 3. GET /api/v1/mockups

List user's mockups with pagination, filtering, and sorting.

**Auth:** x-api-key header or Bearer token (Supabase JWT)

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| limit | integer | 20 | Number of mockups to return (1-100) |
| offset | integer | 0 | Number of mockups to skip |
| name | string | null | Filter by name (case-insensitive contains) |
| created_after | ISO 8601 | null | Filter by creation date (after) |
| created_before | ISO 8601 | null | Filter by creation date (before) |
| sort | enum | "created_at" | Sort field: name, created_at, updated_at |
| order | enum | "desc" | Sort order: asc, desc |

**Response (200):**
```json
{
  "success": true,
  "data": {
    "mockups": [
      {
        "uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
        "name": "T-Shirt Front",
        "thumbnail": "https://cdn.sudomock.com/.../thumb_720.webp",
        "width": 4000,
        "height": 5000,
        "smart_objects": [...],
        "text_layers": [],
        "collections": [],
        "thumbnails": [...]
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}
```

**Error Responses:**
- 401: Invalid or missing authentication
- 429: Rate limit exceeded

---

### 4. GET /api/v1/mockups/{uuid}

Get single mockup detail. Returns the exact same format as the upload response.

**Auth:** x-api-key header or Bearer token

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | string (UUID) | Mockup UUID (min 36 chars) |

**Response (200):** Same format as POST /api/v1/psd/upload response.

**Error Responses:**
- 401: Invalid or missing authentication
- 404: Mockup not found
- 429: Rate limit exceeded

---

### 5. PATCH /api/v1/mockups/{uuid}

Update mockup name. Returns the full mockup response.

**Auth:** x-api-key header or Bearer token

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| uuid | string (UUID) | Mockup UUID |

**Request Body:**
```json
{
  "name": "Updated Mockup Name"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | New mockup name (1-255 characters) |

**Response (200):** Same format as POST /api/v1/psd/upload response (with updated name).

**Error Responses:**
- 401: Invalid or missing authentication
- 404: Mockup not found
- 429: Rate limit exceeded

---

### 6. DELETE /api/v1/mockups/{mockup_uuid}

Permanently delete a mockup and all associated files (layers, thumbnails, masks).

**Auth:** x-api-key header or Bearer token

**Path Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| mockup_uuid | string (UUID) | Mockup UUID to delete |

**Response:** 204 No Content (empty body on success)

**Error Responses:**
- 401: Invalid or missing authentication
- 404: Mockup not found
- 429: Rate limit exceeded

---

### 7. GET /api/v1/me

Get current user account information including subscription, usage, and API key metadata.

**Auth:** x-api-key header

**Response (200):**
```json
{
  "success": true,
  "data": {
    "account": {
      "uuid": "user-uuid",
      "email": "user@example.com",
      "name": "John Doe",
      "created_at": "2025-01-15T10:00:00Z"
    },
    "subscription": {
      "plan": "pro-10k",
      "tier": "pro",
      "status": "active",
      "current_period_end": "2026-04-15T10:00:00Z",
      "cancel_at_period_end": false
    },
    "usage": {
      "credits_used_this_month": 3420,
      "credits_limit": 10000,
      "credits_remaining": 6580,
      "billing_period_start": "2026-03-15T10:00:00Z",
      "billing_period_end": "2026-04-15T10:00:00Z"
    },
    "api_key": {
      "name": "Production Key",
      "created_at": "2025-06-01T10:00:00Z",
      "last_used_at": "2026-03-22T14:30:00Z",
      "total_requests": 125000
    }
  }
}
```

**Error Responses:**
- 401: Invalid or missing API key

---

### 8. POST /api/v1/api-keys

Generate a new API key. The key is only shown once in the response.

**Auth:** Bearer token (Supabase JWT) -- NOT x-api-key

**Request Body:**
```json
{
  "name": "Production Key",
  "expires_in_days": 365
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Display name for the key (1-255 chars) |
| expires_in_days | integer | No | Days until expiration (1-3650). Null = never expires. |

**Response (201):**
```json
{
  "id": "key-id",
  "name": "Production Key",
  "key": "sm_a1b2c3d4e5f6...",
  "is_active": true,
  "last_used_at": null,
  "created_at": "2026-03-22T10:00:00Z",
  "revoked_at": null,
  "expires_at": "2027-03-22T10:00:00Z"
}
```

**Other API Key Endpoints:**
- `GET /api/v1/api-keys` -- List all API keys (Bearer token auth)
- `PATCH /api/v1/api-keys/{key_id}` -- Update key name (Bearer token auth)
- `DELETE /api/v1/api-keys/{key_id}` -- Revoke a key (Bearer token auth)
- `POST /api/v1/api-keys/{key_id}/regenerate` -- Regenerate key (Bearer token auth)

---

### 9. GET /api/v1/packages/plans

Get all available subscription plans with pricing and API limits. No authentication required.

**Response (200):**
```json
{
  "plans": [
    {
      "id": 2,
      "name": "Pro 10K",
      "slug": "pro-10k",
      "tier": "pro",
      "description": "For growing businesses",
      "price_monthly": 37.49,
      "credits_per_month": 10000,
      "max_concurrent_requests": 10,
      "max_concurrent_uploads": 5,
      "stripe_price_id": "price_..."
    }
  ]
}
```

---

### 10. POST /api/v1/studio/create-session

Create a Studio session token for the embeddable customization studio.

**Auth:** x-api-key header or Shopify App Proxy HMAC

**Request Body:**
```json
{
  "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
  "product_id": "shopify-product-123",
  "shop": "mystore.myshopify.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| mockup_uuid | string (UUID) | Yes | UUID of the mockup to customize |
| product_id | string | No | Product ID from your platform |
| shop | string | No | Store domain (used for Shopify HMAC flow) |

**Response (200):**
```json
{
  "success": true,
  "session": "sess_abc123...",
  "expires_in": 900,
  "displayMode": "iframe"
}
```

**Notes:**
- Session tokens are opaque (sess_xxx format) and stored in Redis with 15-minute TTL.
- Sessions auto-extend on every API call (active sessions never expire).
- The API key never leaves the server -- sessions are resolved via Redis lookup.
- Studio URL: `https://studio.sudomock.com/editor?session=sess_xxx`

---

### 11. POST /api/v1/sudoai/render

AI-powered mockup rendering without a PSD file. Uses AI segmentation to detect the product surface and composite artwork.

**Auth:** x-api-key header
**Credits:** 5 credits per render

**Request Body:**
```json
{
  "source_url": "https://example.com/tshirt-photo.jpg",
  "artwork_url": "https://example.com/user-design.png",
  "product_type": "t-shirt",
  "segment_index": 0,
  "color": "#FF5500",
  "placement": {
    "position": "center",
    "coverage": 60,
    "fit": "contain",
    "rotate": 0
  },
  "adjustments": {
    "brightness": 0,
    "contrast": 0,
    "saturation": 0,
    "vibrance": 0,
    "blur": 0,
    "opacity": 100,
    "blend_mode": "multiply",
    "warp_strength": 0,
    "edge_expand": 0,
    "texture_strength": 0
  },
  "export_options": {
    "image_format": "png",
    "image_size": 1920,
    "quality": 95
  }
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| source_url | string | Yes | URL of the product photo |
| artwork_url | string | Conditional | URL of artwork to place. Required if color is not provided. |
| product_type | string | No | Hint for better detection: "t-shirt", "hoodie", "canvas", "mug", etc. |
| segment_index | integer | No | Pre-selected segment index (0-based) from /segment response |
| print_area_x | integer | No | X coordinate for manual print area selection (requires print_area_y) |
| print_area_y | integer | No | Y coordinate for manual print area selection (requires print_area_x) |
| color | string | No | Color overlay hex (e.g., "#FF0000") |
| placement | object | No | Artwork placement configuration |
| adjustments | object | No | Image adjustment parameters |
| export_options | object | No | Export configuration (same as render endpoint) |

**Response (200):**
```json
{
  "success": true,
  "data": {
    "print_files": [
      {
        "export_path": "https://cdn.sudomock.com/renders/sudoai/uuid.png",
        "duration_ms": 2340,
        "segment_index": 0,
        "confidence": 0.95,
        "export_format": "png"
      }
    ]
  }
}
```

**Notes:**
- AI pipeline: product detection (Gemini) -> segmentation (SAM3) -> perspective analysis -> compositing
- No PSD file needed -- works with any product photo
- Supports perspective correction and displacement mapping for realistic results

---

## Code Examples

### cURL

**Upload PSD:**
```bash
curl -X POST https://api.sudomock.com/api/v1/psd/upload \
  -H "Content-Type: application/json" \
  -H "x-api-key: sm_your_api_key" \
  -d '{
    "psd_file_url": "https://your-storage.com/mockup.psd",
    "psd_name": "T-Shirt Front"
  }'
```

**Render Mockup:**
```bash
curl -X POST https://api.sudomock.com/api/v1/renders \
  -H "Content-Type: application/json" \
  -H "x-api-key: sm_your_api_key" \
  -d '{
    "mockup_uuid": "c315f78f-d2c7-4541-b240-a9372842de94",
    "smart_objects": [{
      "uuid": "128394ee-6758-4f2f-aa36-e2b19b152bd9",
      "asset": {
        "url": "https://your-cdn.com/design.png",
        "fit": "cover"
      }
    }],
    "export_options": {
      "image_format": "webp",
      "image_size": 1920,
      "quality": 95
    }
  }'
```

**List Mockups:**
```bash
curl -X GET "https://api.sudomock.com/api/v1/mockups?limit=10&offset=0" \
  -H "x-api-key: sm_your_api_key"
```

**Get Account Info:**
```bash
curl -X GET https://api.sudomock.com/api/v1/me \
  -H "x-api-key: sm_your_api_key"
```

**Delete Mockup:**
```bash
curl -X DELETE https://api.sudomock.com/api/v1/mockups/c315f78f-d2c7-4541-b240-a9372842de94 \
  -H "x-api-key: sm_your_api_key"
```

### Python

```python
import requests

API_KEY = "sm_your_api_key"
BASE_URL = "https://api.sudomock.com/api/v1"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-key": API_KEY,
}

# Step 1: Upload PSD
upload_response = requests.post(
    f"{BASE_URL}/psd/upload",
    headers=HEADERS,
    json={
        "psd_file_url": "https://your-storage.com/mockup.psd",
        "psd_name": "T-Shirt Front",
    },
)
upload_data = upload_response.json()["data"]
mockup_uuid = upload_data["uuid"]
smart_object_uuid = upload_data["smart_objects"][0]["uuid"]
print(f"Uploaded: {mockup_uuid}")

# Step 2: Render with artwork
render_response = requests.post(
    f"{BASE_URL}/renders",
    headers=HEADERS,
    json={
        "mockup_uuid": mockup_uuid,
        "smart_objects": [
            {
                "uuid": smart_object_uuid,
                "asset": {
                    "url": "https://your-cdn.com/design.png",
                    "fit": "cover",
                },
            }
        ],
        "export_options": {
            "image_format": "webp",
            "image_size": 1920,
            "quality": 95,
        },
    },
)
render_url = render_response.json()["data"]["print_files"][0]["export_path"]
print(f"Rendered: {render_url}")

# Step 3: Check account usage
me_response = requests.get(f"{BASE_URL}/me", headers=HEADERS)
usage = me_response.json()["data"]["usage"]
print(f"Credits remaining: {usage['credits_remaining']}/{usage['credits_limit']}")
```

> **Official Python SDK:** For simpler code, use `pip install sudomock`:
> ```python
> from sudomock import SudoMock
>
> client = SudoMock(api_key="sm_your_api_key")
> result = client.render(
>     mockup_uuid="c315f78f-...",
>     smart_objects=[{"uuid": "128394ee-...", "asset": {"url": "https://your-cdn.com/design.png"}}],
> )
> print(result.print_files[0].export_path)
> ```

### Node.js

```javascript
const API_KEY = process.env.SUDOMOCK_API_KEY;
const BASE_URL = 'https://api.sudomock.com/api/v1';

async function sudomockRequest(path, options = {}) {
  const response = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.detail || `HTTP ${response.status}`);
  }

  if (response.status === 204) return null;
  return response.json();
}

// Step 1: Upload PSD
const upload = await sudomockRequest('/psd/upload', {
  method: 'POST',
  body: JSON.stringify({
    psd_file_url: 'https://your-storage.com/mockup.psd',
    psd_name: 'T-Shirt Front',
  }),
});

const mockupUuid = upload.data.uuid;
const soUuid = upload.data.smart_objects[0].uuid;
console.log('Uploaded:', mockupUuid);

// Step 2: Render
const render = await sudomockRequest('/renders', {
  method: 'POST',
  body: JSON.stringify({
    mockup_uuid: mockupUuid,
    smart_objects: [{
      uuid: soUuid,
      asset: { url: 'https://your-cdn.com/design.png', fit: 'cover' },
    }],
    export_options: { image_format: 'webp', image_size: 1920, quality: 95 },
  }),
});

console.log('Rendered:', render.data.print_files[0].export_path);

// Step 3: List mockups with filtering
const mockups = await sudomockRequest('/mockups?limit=10&sort=created_at&order=desc');
console.log(`Total mockups: ${mockups.data.total}`);

// Step 4: Render with color overlay (for fabric mockups)
const colorRender = await sudomockRequest('/renders', {
  method: 'POST',
  body: JSON.stringify({
    mockup_uuid: mockupUuid,
    smart_objects: [{
      uuid: soUuid,
      asset: { url: 'https://your-cdn.com/design.png', fit: 'cover' },
      color: { hex: '#FF5733', blending_mode: 'multiply' },
    }],
  }),
});

// Step 5: Render with base64 (fastest)
const base64Image = Buffer.from(imageBuffer).toString('base64');
const fastRender = await sudomockRequest('/renders', {
  method: 'POST',
  body: JSON.stringify({
    mockup_uuid: mockupUuid,
    smart_objects: [{
      uuid: soUuid,
      asset: { base64: base64Image, content_type: 'image/png', fit: 'cover' },
    }],
  }),
});
```

> **Note:** The raw API examples above use snake_case field names (e.g., `mockup_uuid`, `smart_objects`), which is the correct format for the REST API.
>
> **Official Node.js SDK:** For simpler code, use `npm install sudomock`:
> ```javascript
> import { SudoMock } from 'sudomock';
>
> const client = new SudoMock({ apiKey: 'sm_your_api_key' });
> const result = await client.render({
>   mockupUuid: 'c315f78f-...',
>   smartObjects: [{ uuid: '128394ee-...', asset: { url: 'https://your-cdn.com/design.png' } }],
> });
> console.log(result.printFiles[0].exportPath);
> ```
> The SDK uses camelCase (JavaScript convention), while the REST API uses snake_case. Both are correct for their respective contexts.

### n8n Workflow

1. **HTTP Request node** (Upload PSD):
   - Method: POST
   - URL: `https://api.sudomock.com/api/v1/psd/upload`
   - Header: `x-api-key: {{ $env.SUDOMOCK_API_KEY }}`
   - Body: `{ "psd_file_url": "{{ $json.psd_url }}" }`

2. **HTTP Request node** (Render):
   - Method: POST
   - URL: `https://api.sudomock.com/api/v1/renders`
   - Header: `x-api-key: {{ $env.SUDOMOCK_API_KEY }}`
   - Body:
   ```json
   {
     "mockup_uuid": "{{ $json.data.uuid }}",
     "smart_objects": [{
       "uuid": "{{ $json.data.smart_objects[0].uuid }}",
       "asset": { "url": "{{ $json.design_url }}" }
     }]
   }
   ```

3. **Output**: `{{ $json.data.print_files[0].export_path }}` -- rendered mockup URL

---

## Pricing Structure

### Dashboard Usage
- **500 one-time API credits included** to get started
- No credit card required
- No limits on mockup generation via the web dashboard

### API Usage
| Tier | Credits | Price | Parallel Renders | Per Render |
|------|---------|-------|------------------|------------|
| Starter 5K | 5,000 | $17.49/mo | 3 | $0.0035 |
| Starter 10K | 10,000 | $27.49/mo | 3 | $0.0027 |
| Starter 25K | 25,000 | $57.49/mo | 3 | $0.0023 |
| Starter 50K | 50,000 | $101.24/mo | 3 | $0.0020 |
| Starter 100K | 100,000 | $179.99/mo | 3 | $0.0018 |
| Pro 5K | 5,000 | $27.49/mo | 10 | $0.0055 |
| Pro 10K | 10,000 | $37.49/mo | 10 | $0.0037 |
| Pro 25K | 25,000 | $67.49/mo | 10 | $0.0027 |
| Pro 50K | 50,000 | $111.24/mo | 10 | $0.0022 |
| Pro 100K | 100,000 | $189.99/mo | 10 | $0.0019 |
| Scale 5K | 5,000 | $52.49/mo | 25 | $0.0105 |
| Scale 10K | 10,000 | $62.49/mo | 25 | $0.0062 |
| Scale 25K | 25,000 | $92.49/mo | 25 | $0.0037 |
| Scale 50K | 50,000 | $136.24/mo | 25 | $0.0027 |
| Scale 100K | 100,000 | $214.99/mo | 25 | $0.0021 |

**Parallel Limits by Tier:**
- Included (no subscription): 1 parallel render, 1 parallel upload
- Starter: 3 parallel renders, 2 parallel uploads
- Pro: 10 parallel renders, 5 parallel uploads
- Scale: 25 parallel renders, 10 parallel uploads

**Cost Comparison (10,000 renders/month):**
- Adobe Photoshop API: $1,500/month
- DynamicMockups: ~$500/month
- SudoMock (Pro): $37.49/month

---

## MCP Server (Model Context Protocol)

SudoMock provides an MCP server for AI assistants and LLM agents to interact with the API programmatically.

### Connection Details
- **Endpoint:** https://mcp.sudomock.com
- **Transport:** Streamable HTTP (stateless, load-balancer safe)
- **Auth:** OAuth 2.1 (Supabase JWT) or sm_ API key

### Packages
- **npm:** `@sudomock/mcp`
- **PyPI:** `sudomock`

### Quick Start with npx
```bash
npx @sudomock/mcp
```

### Available MCP Tools
- `upload_psd` -- Upload and process a PSD file
- `render_mockup` -- Render a mockup with artwork
- `ai_render` -- AI-powered render (no PSD needed)
- `list_mockups` -- List user's mockups
- `get_mockup_details` -- Get mockup details
- `update_mockup` -- Update mockup name
- `delete_mockup` -- Delete a mockup
- `get_account` -- Get account info and usage
- `create_studio_session` -- Create a Studio session

### Available MCP Resources
- `quickstart_guide` -- Getting started documentation
- `pricing_info` -- Current pricing information
- `supported_formats` -- Supported file formats and blend modes

### Available MCP Prompts
- `render_product_mockups` -- Guided workflow for rendering product mockups
- `troubleshoot_render` -- Debug rendering issues

---

## Integration Guides

### Shopify App
- Native Shopify app from the Shopify App Store
- One-click "Customize This Product" button on product pages
- Real-time mockup customization studio embedded in storefront
- Product mapping: assign PSD mockups to Shopify products
- Theme Editor integration: drag-and-drop App Block
- Shopify Online Store 2.0 compatible
- Install: https://sudomock.com/integrations/shopify

### WooCommerce Plugin
- Free WordPress plugin
- Product Customizer block for WooCommerce stores
- Popup-based customization studio
- Product-level mockup mapping via WooCommerce product tab
- HPOS (High-Performance Order Storage) compatible
- Block and classic theme support
- 10 languages included
- Install: https://sudomock.com/integrations/woocommerce

### n8n
- HTTP Request nodes for upload and render
- Expression support for dynamic design URLs
- Chain with Shopify, Etsy, Amazon nodes for automated listing creation
- Docs: https://sudomock.com/docs/integrations/n8n

### Zapier
- Trigger renders from Zap triggers (new Shopify order, new file in Google Drive, etc.)
- Docs: https://sudomock.com/docs/integrations/zapier

### Make (Integromat)
- HTTP module integration with SudoMock API
- Docs: https://sudomock.com/docs/integrations/make

### Airtable
- Script block integration for batch rendering
- Docs: https://sudomock.com/docs/integrations/airtable

### Google Sheets
- Apps Script integration for bulk mockup generation
- Docs: https://sudomock.com/docs/integrations/google-sheets

---

## Error Codes Reference

### HTTP Status Codes

| Code | Status | Description |
|------|--------|-------------|
| 200 | OK | Request successful |
| 201 | Created | Resource created (API key generation) |
| 204 | No Content | Success, no body (delete operations) |
| 400 | Bad Request | Invalid request format, missing fields, malformed JSON, or PSD file too large (exceeds 300MB) |
| 401 | Unauthorized | Invalid or missing API key (x-api-key) or Bearer token |
| 402 | Payment Required | Insufficient credits |
| 404 | Not Found | Resource not found (check mockup_uuid, smart_object_uuid, key_id) |
| 422 | Validation Error | Request body validation failed (field types/constraints) |
| 429 | Too Many Requests | Rate limit or concurrent limit exceeded |
| 500 | Internal Server Error | Unexpected error (safe to retry with backoff) |
| 502 | Bad Gateway | Cannot download user's image from provided URL |

### Error Response Format

Standard errors (400, 401, 404, 500):
```json
{
  "success": false,
  "detail": "Human-readable error message"
}
```

Validation errors (422):
```json
{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "Error description",
      "type": "error_type"
    }
  ]
}
```

Credit errors (402):
```json
{
  "detail": "Insufficient credits",
  "error": {
    "type": "insufficient_credits",
    "credits_required": 1,
    "credits_remaining": 0
  }
}
```

Rate limit errors (429):
```json
{
  "detail": "Rate limit exceeded. Please slow down and try again.",
  "error": {
    "type": "rate_limit_exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "limit": 1000,
    "remaining": 0,
    "retry_after": 42
  }
}
```

Concurrent limit errors (429):
```json
{
  "detail": "Max concurrent render requests exceeded. Your plan (Pro) allows 10 concurrent render request(s).",
  "error": {
    "type": "concurrent_limit_exceeded",
    "code": "CONCURRENT_LIMIT_EXCEEDED",
    "limit": 10,
    "current": 11,
    "remaining": 0,
    "resource": "concurrent-render"
  }
}
```

### Rate Limit Response Headers (IETF Standard)

| Header | Description | Example |
|--------|-------------|---------|
| RateLimit-Limit | Maximum requests per window | 1000 |
| RateLimit-Remaining | Requests remaining in window | 487 |
| RateLimit-Reset | Seconds until window resets | 30 |
| Retry-After | Seconds to wait before retrying (429 only) | 5 |

### Retry Strategy
- **Always retry:** 429, 500, 502, 503, 504, network errors
- **Never retry:** 400, 401, 404, 422 (fix the request first)
- Use exponential backoff: 1s, 2s, 4s between retries
- Respect the Retry-After header for 429 responses

### Field Constraints (triggers 422 on violation)

| Field | Type | Constraints |
|-------|------|-------------|
| export_options.image_size | integer | 100-10000 |
| export_options.quality | integer | 1-100 |
| export_options.image_format | enum | png, jpg, webp |
| smart_objects[].asset.fit | enum | fill, contain, cover |
| smart_objects[].asset.rotate | integer | -360 to 360 |
| adjustment_layers.brightness | integer | -150 to 150 |
| adjustment_layers.contrast | integer | -100 to 100 |
| adjustment_layers.saturation | integer | -100 to 100 |
| adjustment_layers.vibrance | integer | -100 to 100 |
| adjustment_layers.opacity | integer | 0-100 |
| adjustment_layers.blur | integer | 0-100 |
| color.hex | string | Pattern: ^#[0-9A-Fa-f]{6}$ |
| api_key.name | string | 1-255 characters |
| api_key.expires_in_days | integer | 1-3650 (or null) |

---

## Supported Blend Modes (Complete List)

SudoMock implements all 29 Photoshop blend modes with mathematical accuracy:

### Normal/Special
- Normal, Pass Through, Dissolve

### Darken Modes
- Darken, Multiply, Color Burn, Linear Burn, Darker Color

### Lighten Modes
- Lighten, Screen, Color Dodge, Linear Dodge (Add), Add, Lighter Color

### Contrast Modes
- Overlay, Soft Light, Hard Light, Vivid Light, Linear Light, Pin Light, Hard Mix

### Inversion Modes
- Difference, Exclusion, Subtract, Divide

### HSL Component Modes
- Hue, Saturation, Color, Luminosity

### Usage Recommendations
- **Multiply**: Ideal for fabric mockups (t-shirts, hoodies) -- blends design into fabric texture naturally
- **Normal**: Best for flat/hard surfaces (phone cases, mugs, packaging)
- **Screen**: Perfect for light designs on dark backgrounds
- **Overlay**: Creates depth with mid-tone contrast enhancement
- **Soft Light**: Subtle texture blending for realistic product shots
- **Color Burn**: Deep shadow integration on dark fabrics

---

## Professional Rendering Capabilities

- **29 Photoshop Blend Modes**: Full support (see list above)
- **Unlimited Layers**: No artificial restrictions -- complex PSD hierarchies supported
- **Layer Effects**: Drop Shadow, Stroke, Blend If (advanced shadow/highlight control)
- **Smart Objects**: Nested Smart Objects, multiple Smart Objects per template, warp/perspective transform support
- **High Resolution**: Print-ready output (up to 10,000px width)
- **Export Formats**: WebP (recommended, 30-70% smaller), PNG (lossless), JPEG (smallest)
- **Max PSD File Size**: 300 MB
- **Max Output Dimension**: 10,000 x 10,000 pixels

---

## Custom Domain (White-Label CDN)

SudoMock is the only mockup platform offering custom domain support for rendered images.

### How It Works
- Default: Rendered mockups served from cdn.sudomock.com
- Custom Domain: Connect your own domain (e.g., renders.yourbrand.com) via dashboard
- All rendered image URLs use YOUR domain -- zero SudoMock branding
- Point CNAME to SudoMock CDN, SSL automatically provisioned
- Setup: Dashboard > Domains > Add custom domain

### Storage Tiers
- **cdn-renders/ path**: Permanent storage (custom domain users)
- **Standard renders**: 7-day storage, automatically cleaned up

---

## Mockup Library

Free professionally crafted mockup templates:
- Browse: https://sudomock.com/mockups

### Categories
- Apparel: https://sudomock.com/mockups/apparel
- Accessories: https://sudomock.com/mockups/accessories
- Home & Living: https://sudomock.com/mockups/home-living
- Drinkware: https://sudomock.com/mockups/drinkware
- Devices: https://sudomock.com/mockups/devices
- Print & Paper: https://sudomock.com/mockups/print-paper
- Packaging: https://sudomock.com/mockups/packaging
- Branding: https://sudomock.com/mockups/branding
- Signage & Advertising: https://sudomock.com/mockups/signage-advertising
- Social Media & Digital: https://sudomock.com/mockups/social-media-digital

### Browse by Facet
- By Tag: https://sudomock.com/mockups/tag
- By Style: https://sudomock.com/mockups/style
- By Audience: https://sudomock.com/mockups/for
- By Platform: https://sudomock.com/mockups/platform
- By Industry: https://sudomock.com/mockups/industry
- By Use Case: https://sudomock.com/mockups/use-case
- By Season: https://sudomock.com/mockups/season

---

## Links

- **Website:** https://sudomock.com
- **API Docs:** https://sudomock.com/docs
- **Quick Start:** https://sudomock.com/docs/quickstart
- **Pricing:** https://sudomock.com/pricing
- **Blog:** https://sudomock.com/blog
- **Status Page:** https://sudomock.statuspage.io

### Native Integrations
- Shopify App: https://sudomock.com/integrations/shopify
- WooCommerce Plugin: https://sudomock.com/integrations/woocommerce
- All Integrations: https://sudomock.com/integrations

### Social
- YouTube: https://youtube.com/@sudomock
- Twitter/X: https://twitter.com/sudomock
- GitHub: https://github.com/sudomock

### Contact
- General: hello@sudomock.com
- Legal: legal@sudomock.com
- Enterprise: corporate@sudomock.com

### Company
SudoMock is a registered DBA operated under a New Mexico LLC.
Address: 1209 Mountain Rd Pl NE, Ste N, Albuquerque, NM 87110, USA

---

*Last updated: March 2026. This document contains the complete SudoMock API and platform documentation for LLM consumption. For human-readable docs with interactive examples, visit https://sudomock.com/docs*