> ## 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.

# Upload a PSD

> Register a template once and read back every slot in it.

Uploading registers a Photoshop file as a reusable template. You do it once per
template, and every render afterwards refers to it by UUID. The response is the
only discovery step there is: it lists every slot the file holds, with the
handles you send back at render time.

<Info>
  The file is fetched server side, so the URL has to answer without a session
  cookie. A signed URL that expires works.
</Info>

## Register the template

<Steps>
  <Step title="Host the PSD at a URL the API can fetch.">
    Object storage, a CDN or a signed link all work. The fetch timeout is in
    the table below.
  </Step>

  <Step title="Send that URL to the upload endpoint.">
    One `POST` with `psd_file_url` and an optional `psd_name`. [Create a mockup
    from a PSD](/docs/api-reference/psd-mockups/create-a-mockup-from-a-psd) carries
    that request in eight languages, with the whole response body. Every call
    carries your API key. See [Authentication](/docs/authentication).
  </Step>

  <Step title="Read the template UUID back." />

  <Step title="Read the slot arrays beside it.">
    `smart_objects`, `text_layers` and `group_layers` each list what the
    designer built, one entry and one UUID per addressable layer.
  </Step>

  <Step title="Store those UUIDs against the names your own product uses.">
    A render addresses a slot by UUID, not by layer name, so the mapping is
    yours to keep.
  </Step>
</Steps>

| Field          | Required | Notes                                                                         |
| -------------- | -------- | ----------------------------------------------------------------------------- |
| `psd_file_url` | Yes      | Public or signed URL to the file. Fetched with a 300 second timeout.          |
| `psd_name`     | No       | Up to 255 characters. Derived from the filename when omitted.                 |
| `is_async`     | No       | `true` returns `202` with a `job_id` instead of waiting. Defaults to `false`. |

## What comes back

One response carries every UUID a render needs.

| Field                               | What it holds                                                             |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `data.uuid`                         | The template handle. A render sends it as `mockup_uuid`.                  |
| `data.name`                         | The template name, as you sent it or as the filename gave it.             |
| `data.width`, `data.height`         | The canvas the template renders at.                                       |
| `data.smart_objects`                | One entry per visible design area, each with its own UUID.                |
| `data.text_layers`                  | One entry per live type layer, with its current wording, font and colour. |
| `data.group_layers`                 | Enclosing groups whose outline a render can recolour.                     |
| `data.thumbnail`, `data.thumbnails` | A preview image, and that same preview at three widths.                   |

Author artwork at a design area's `size`. The render scales it into `position`
for you, so neither number belongs in a render body. `quad`, the four corner
points of an area with a perspective transform, arrives on Scale plans and is
`null` on lower ones.

## Uploading in the background

A large PSD takes a while to read. Send `"is_async": true` and the call answers
at once with a job rather than a template: a `job_id`, the job `kind`, its
`status` and a `status_url`. [Retrieve a single
job](/docs/api-reference/jobs/retrieve-a-single-job) returns that job once it
finishes, carrying the new `mockup_uuid`.

Register a [webhook endpoint](/docs/webhooks/overview) and the `upload.succeeded`
event arrives instead, with no polling. Send an `Idempotency-Key` header either
way, so a retried upload does not register the same template twice.

## Practical notes

Upload once per template, not once per render. Re-uploading the same file
produces a second template with its own UUIDs and spends the time again.

Uploads that contain hidden smart objects come back flagged, because a hidden
smart object is not exposed as a slot. Make it visible in Photoshop and upload
again. See [Hidden layers](/docs/faq/why-did-my-hidden-layer-not-render).

Upload failures return `error_code`, `message` and `detail`. A file that cannot
be fetched, a file that is not a PSD, and a file with no addressable layer each
have their own code, listed in [Errors](/docs/errors).

## Learn more

<CardGroup cols={2}>
  <Card title="Smart objects" icon="layers" href="/docs/psd-mockups/smart-objects">
    Read what each field on a design area describes.
  </Card>

  <Card title="Text layers" icon="type" href="/docs/text/text-layers">
    Change wording, font, size and colour on every render.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Render a PSD" icon="image" href="/docs/psd-mockups/render-a-psd-without-photoshop">
    Take those UUIDs and produce a finished image.
  </Card>

  <Card title="Create a mockup from a PSD" icon="terminal" href="/docs/api-reference/psd-mockups/create-a-mockup-from-a-psd">
    See the request and the whole response body.
  </Card>
</CardGroup>