> ## Documentation Index
> Fetch the complete documentation index at: https://sudomock.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The base URL is https://api.sudomock.com.
> Authenticate every request with the x-api-key header. Keys begin with sm_.
> A render returns the finished image at data.print_files[0].export_path. A request sent with is_async true returns a job_id to poll at GET /api/v1/jobs/{job_id}.
> Prefer the official SDKs over hand-written HTTP calls: npm install sudomock for Node, pip install sudomock for Python.

# Quickstart

> From a Photoshop file to a rendered mockup in two requests.

<Prompt description="Use this pre-built prompt to get an agent calling the SudoMock API correctly." icon="sparkles" actions={["copy", "cursor"]}>
  # Render a mockup with the SudoMock API

  **Purpose:** Enforce only the current and correct instructions for turning a
  Photoshop template into a rendered mockup with the
  [SudoMock](https://sudomock.com/) API over HTTP.
  **Scope:** All AI-generated advice or code that calls SudoMock without an
  SDK must follow these guardrails.

  ***

  ## **1. Official setup**

  The human first creates an API key at
  [https://sudomock.com/docs/dashboard/api-keys](https://sudomock.com/docs/dashboard/api-keys)
  and has a PSD or PSB reachable over HTTPS. Keys begin with `sm_` and are
  stored in an environment variable called `SUDOMOCK_API_KEY`.

  The base URL is `https://api.sudomock.com`. Every request carries the key in
  `x-api-key: sm_your_api_key`, and that is the only header the API reads for
  authentication.

  ### **Upload the template once**

  ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
  curl -X POST https://api.sudomock.com/api/v1/psd/upload \
    -H "x-api-key: $SUDOMOCK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"psd_file_url": "https://example.com/tee.psd"}'
  ```

  Store `data.uuid` and the `uuid` of every entry in `data.smart_objects`
  and `data.text_layers`. Upload once per template, never once per render.

  ### **Render it**

  ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
  curl -X POST https://api.sudomock.com/api/v1/renders \
    -H "x-api-key: $SUDOMOCK_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mockup_uuid": "MOCKUP_UUID",
      "smart_objects": [
        {
          "uuid": "SMART_OBJECT_UUID",
          "asset": { "url": "https://example.com/art.png" }
        }
      ]
    }'
  ```

  The finished image is at `data.print_files[0].export_path`.

  ***

  ## **2. Request body reference**

  `POST /api/v1/psd/upload` takes `psd_file_url` (`string`, required, HTTPS URL
  of the PSD or PSB), `psd_name` (`string`, optional name for the template) and
  `is_async` (`boolean`, process in the background and return a job).

  `POST /api/v1/renders` takes `mockup_uuid` (`string`, required, template UUID
  from the upload), `smart_objects` (`object[]`, artwork and colour, one entry
  per layer), `text_layers` (`object[]`, replacement copy, one entry per text
  layer), `group_layers` (`object[]`, outline colour of a listed group),
  `hidden_layers` (`string[]`, layer UUIDs to leave out of this render),
  `export_options` (`object`, format, size and quality of the output) and
  `is_async` (`boolean`, enqueue the render and return a job). At least one of
  `smart_objects`, `text_layers`, `group_layers` or `hidden_layers` is
  required.

  `smart_objects[]`: `uuid` (`string`, required, smart object UUID from the
  upload), `asset` (`object`, `url` or `base64`, plus `fit`, `rotate`, `size`),
  `color` (`object`, `hex`, plus an optional `blending_mode`). `fit` is one of
  `fit`, `fill` or `crop`.

  `text_layers[]`: `uuid` (`string`, required, text layer UUID from the
  upload), `text` (`string`, replacement copy, 1 to 500 characters), `font`
  (`string`, font UUID or PostScript name), `fit` (`string`, `shrink`, `clip`
  or `overflow`).

  `export_options`: `image_format` (`png`, `jpg` or `webp`, default `webp`),
  `image_size` (`number`, 100 to 10000 px wide, default `2048`, or `"original"`
  for the PSD's own size and resolution), `quality` (`number`, 1 to 100,
  default `90`). For images you upload to a marketplace
  such as Etsy, use `jpg`: some marketplace upload pipelines read WebP colours
  with reduced contrast, and a JPG arrives as rendered.

  ***

  ## **3. Critical instructions for AI models**

  ### **3.1 - ALWAYS DO THE FOLLOWING**

  1. **Keep the key in the environment** and on the server side only.
  2. **Send it in the `x-api-key` header** on every call, never in
     `Authorization`.
  3. **Use snake\_case** field names on the wire.
  4. **Upload a template once**, store the UUIDs it returns, and render
     against them.
  5. **Read `data.print_files[0].export_path`** for the finished image.

  ### **3.2 - NEVER DO THE FOLLOWING**

  1. **Do not** hardcode an `sm_` key in source, in a bundle, or in any code
     that ships to a browser.
  2. **Do not** invent a field name. If it is not in the documentation, it
     does not exist.
  3. **Do not** retry `400`, `401`, `402`, `403`, `404` or `422`. Fix the
     request or the billing state first, and repeat only `429`, `500` and
     `502`.
  4. **Do not** upload a PSD that is already a template. Render against the
     stored UUID.

  Verify every rule above before returning any SudoMock solution. If a check
  **fails**, **stop** and revise until compliance is achieved.

  Every error code and its retry rule: [https://sudomock.com/docs/errors](https://sudomock.com/docs/errors)

  For the entire docs for SudoMock, see [https://sudomock.com/docs/llms-full.txt](https://sudomock.com/docs/llms-full.txt)
</Prompt>

## Prerequisites

Before you start, you'll need:

* A SudoMock [API key](/docs/dashboard/api-keys)
* A [PSD reachable over HTTPS](/docs/psd-mockups/preparing-a-psd)

## Guide

<Steps>
  <Step title="Set your API key">
    Keys begin with `sm_` and travel in the
    [`x-api-key` header](/docs/authentication). Keep yours in the environment so it
    never reaches a browser.

    ```bash .env theme={"theme":{"light":"github-light","dark":"vesper"}}
    SUDOMOCK_API_KEY=sm_your_api_key
    ```
  </Step>

  <Step title="Upload the template once">
    Send a public URL to your PSD. The response lists the smart objects, text
    layers and group layers it found, each with the UUID you use to address
    it.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST https://api.sudomock.com/api/v1/psd/upload \
      -H "x-api-key: $SUDOMOCK_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "psd_file_url": "https://example.com/tshirt-mockup.psd",
        "psd_name": "T-shirt front"
      }'
    ```

    Keep the mockup UUID at `data.uuid` and the UUID of the smart object you
    want to fill at `data.smart_objects[0].uuid`. Every later render reuses
    them, so this step belongs in your setup, not in your render loop.
  </Step>

  <Step title="Render it">
    The mockup UUID says which template, the smart object UUID says which
    layer, and `asset.url` is the artwork that goes into it.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST https://api.sudomock.com/api/v1/renders \
      -H "x-api-key: $SUDOMOCK_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "mockup_uuid": "YOUR_MOCKUP_UUID",
        "smart_objects": [
          {
            "uuid": "YOUR_SMART_OBJECT_UUID",
            "asset": {
              "url": "https://example.com/artwork.png",
              "fit": "crop"
            }
          }
        ],
        "export_options": {
          "image_format": "webp",
          "image_size": 1920,
          "quality": 90
        }
      }'
    ```

    The finished image is at `data.print_files[0].export_path`.
  </Step>
</Steps>

The same template takes new artwork, a different colour through
`smart_objects[].color` or different copy through `text_layers[]`, each as
another render against the same UUID.
[Render a PSD mockup](/docs/api-reference/psd-mockups/render-a-psd-mockup) carries
every field of that call, and a render that runs long can return a job and
[call you back](/docs/webhooks/overview) instead of holding the connection.

## Examples

<CardGroup cols={3}>
  <Card title="Node.js" icon="square-arrow-out-up-right" href="/docs/render-with-nodejs">
    Render from a Node service
  </Card>

  <Card title="Python" icon="square-arrow-out-up-right" href="/docs/render-with-python">
    Render from a Python service
  </Card>

  <Card title="SDKs" icon="square-arrow-out-up-right" href="/docs/sdks">
    The official Node and Python clients
  </Card>

  <Card title="Render a PSD mockup" icon="square-arrow-out-up-right" href="/docs/api-reference/psd-mockups/render-a-psd-mockup">
    Every field of the render call
  </Card>

  <Card title="Text layers" icon="square-arrow-out-up-right" href="/docs/text/text-layers">
    Replace copy without new artwork
  </Card>

  <Card title="Fit and blend modes" icon="square-arrow-out-up-right" href="/docs/concepts/fit-and-blend-modes">
    How artwork meets a print area
  </Card>

  <Card title="Render a photo mockup" icon="square-arrow-out-up-right" href="/docs/api-reference/photo-mockups/render-a-photo-mockup">
    Print onto a product photo
  </Card>

  <Card title="Retrieve a single job" icon="square-arrow-out-up-right" href="/docs/api-reference/jobs/retrieve-a-single-job">
    Collect a background render
  </Card>

  <Card title="Webhooks" icon="square-arrow-out-up-right" href="/docs/webhooks/overview">
    Get called back when a render finishes
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.