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

# Smart objects

> How a PSD design area is described and addressed.

A smart object is a Photoshop layer that holds image data as a container rather
than as flat pixels. In a mockup template it marks where artwork goes. Uploading
a PSD returns one entry per visible smart object, and that entry is how you
address the area at render time.

<Info>
  Upload lists visible smart objects only. Turn on every layer you plan to fill
  before you send the file.
</Info>

## What an entry describes

An entry carries the layer as the designer built it, plus the handle you send
back. [Upload a PSD](/docs/psd-mockups/upload-a-psd) walks through the call, and
[Create a mockup from a PSD](/docs/api-reference/psd-mockups/create-a-mockup-from-a-psd)
shows the whole response body next to the request that produced it.

| Field                | What it tells you                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| `uuid`               | The handle you send back in a render.                                                                        |
| `name`, `layer_name` | The layer as the designer named it. `layer_name` is the raw PSD name.                                        |
| `size`               | The area's own width and height. Author artwork at these numbers.                                            |
| `position`           | Where the area lands on the canvas after transforms, as `x`, `y`, `width` and `height`. Use it for previews. |
| `quad`               | The four corner points when the area carries a perspective transform. Included on Scale plans.               |
| `blend_mode`         | The blend mode the layer was authored with.                                                                  |
| `required`           | Whether the template expects this area to be filled.                                                         |

## Address an area in a render

A render takes the template's `mockup_uuid` and a `smart_objects` array. Send
one entry per area you want to change, keyed on the `uuid` that upload gave you,
and leave the rest out. Anything you omit renders as the designer authored it. A
template can hold as many areas as the designer built, including smart objects
nested inside other smart objects, and a single render can fill several of them
at once.

Every entry needs an `asset`, a `color`, or both, and an entry that carries
neither comes back as `422`. The same entry can also carry a colour overlay and
adjustment values alongside the artwork, so one area can change image, tint and
tone in one pass. [Artwork placement](/docs/psd-mockups/artwork-placement) takes fit,
size, position, rotation, colour and tone field by field,
[Fit and blend modes](/docs/concepts/fit-and-blend-modes) covers how artwork meets an
area, and [Render a PSD mockup](/docs/api-reference/psd-mockups/render-a-psd-mockup)
holds the request and response shapes.

## Match slots by name, not by order

Array order follows the Photoshop layer stack, so a designer who reorders layers
changes it, and code that reaches for the first entry quietly starts filling the
wrong area. Build a lookup from the names your template is authored with: read
`name` on each entry, keep the `uuid` it belongs to, and resolve the slot by
name when you render. If a name your code expects is not in the template, fail
loudly instead of falling back to a position, because that fallback ships a
wrong print file rather than an error.

## Linked and hidden smart objects

A smart object whose content lives in an external file, such as `@artwork.psb`,
uploads and renders from its placement geometry, so you do not need to run Embed
Linked first. Embedding still gives the highest fidelity. When a linked smart
object carries no usable placement geometry, the render returns a permanent
`422` with `LINKED_SMART_OBJECT_CONTENT_MISSING`. That one does not clear on
retry. Run **Layer > Smart Objects > Embed Linked** in Photoshop and upload the
file again, or send the artwork in the render body.
[Errors](/docs/errors) lists every code and says which are worth retrying.

A smart object that is hidden in Photoshop is not exposed as a slot and is not
rendered. Uploads that contain one come back flagged, so you know which layers
to turn on before uploading again. Hidden text layers behave differently, and
both rules are on
[Hidden layers](/docs/faq/why-did-my-hidden-layer-not-render).

## Learn more

<CardGroup cols={2}>
  <Card title="Artwork placement" icon="move" href="/docs/psd-mockups/artwork-placement">
    Set fit, size, position, rotation, colour and tone on an area.
  </Card>

  <Card title="Fit and blend modes" icon="layers" href="/docs/concepts/fit-and-blend-modes">
    See how artwork meets an area and sits on the material.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Upload a PSD" icon="upload" href="/docs/psd-mockups/upload-a-psd">
    Send a template and read back the areas it exposes.
  </Card>

  <Card title="Render a PSD mockup" icon="image" href="/docs/api-reference/psd-mockups/render-a-psd-mockup">
    Fill an area and get the print file back.
  </Card>
</CardGroup>