> ## 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.
# Print areas and surfaces
> Where artwork can land on a photo mockup, and how to move it.
A photo mockup carries two kinds of render target, and every render names
exactly one of them per artwork.
* A **print area** is a bounded zone drawn on a product, a chest panel or a
poster face. It is four corner points, and it is addressed by
`print_area_id`.
* A **surface** is a whole printable product in the photograph. It is addressed
by `surface_uuid`, and it is how you print across the entire item.
Drawing a print area on a product does not take its surface away. The same
t-shirt can hold a logo zone and still accept an all over print, which is why a
mockup usually returns both lists.
The areas prepared when a mockup is created are ready to render as they are.
Reach for the write endpoint only when you want your own placement.
## What a mockup returns
Both lists come back on the create response and on
[Retrieve a single photo mockup](/docs/api-reference/photo-mockups/retrieve-a-single-photo-mockup).
| Field | What it holds |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `source_width`, `source_height` | The pixel size of the photograph. Every point is in this space. |
| `quads[].print_area_id` | The id you send to print inside a bounded zone. |
| `quads[].points` | Four `[x, y]` corners, ordered top left, top right, bottom right, bottom left. |
| `quads[].name` | The label the area was saved under, such as `Front`. |
| `quads[].sort_order` | The area's place in the photograph, counted from zero. |
| `surfaces[].surface_uuid` | The id you send to print across the whole product. |
| `surfaces[].points` | The four corners of that product in the photograph. |
| `surfaces[].bbox` | The same product as `x`, `y`, `width` and `height`. |
A quad has to be convex and sit inside the photograph. `sort_order` follows the
photograph rather than your array: areas are ordered by their leftmost point,
then top to bottom, so index zero is the leftmost area on the image. Read the
order off the response instead of assuming it.
## Set your own areas
Two calls write a `print_areas` array, and the choice between them is timing.
Each entry carries its four `points` and an optional `name`.
Send the array with
[Create a mockup from a product photo](/docs/api-reference/photo-mockups/create-a-mockup-from-a-product-photo)
when you already know where artwork belongs. SudoMock uses those areas exactly
and skips detection, which keeps a bulk import deterministic.
Send it to
[Replace the print areas of a photo mockup](/docs/api-reference/photo-mockups/replace-the-print-areas-of-a-photo-mockup)
when a prepared mockup needs moving. That call replaces the whole list in the
order you send, so include every area you mean to keep. It answers with a
`print_areas` list rather than `quads`, and each saved area carries the
`print_area_id` you render against alongside its `points`, `name` and
`sort_order`. An empty array removes every bounded zone. The product surface
stays, so the mockup still renders as a whole item.
A mockup holds at most eight print areas, and a single render names at most
eight targets. Split a product that needs more into a second mockup of the same
photograph.
Areas can be written only once the mockup reports `status: "ready"`. A write
sent earlier returns `409` with `MOCKUP_NOT_SETTABLE`; wait for the create job
to finish and send it again. Points are validated against the source image
rather than against the product, so a quad falling outside `source_width` or
`source_height` is rejected with `400` rather than clamped, at setup instead of
in a render. Both statuses are listed in [Errors](/docs/errors).
## Review placement by eye
Numbers are the fast path, and a photograph sometimes needs a look. The mockup
editor at
[Dashboard, Photo mockups](https://sudomock.com/dashboard/photo-to-mockup)
opens the prepared result, lets you drag the corners, and saves the areas the
endpoint writes. Its Code tab prints a ready to run request carrying the real
`mockup_id` and target id.
## Print areas on a PSD template
A PSD mockup marks placement differently. A smart object can carry
`print_area_presets`, named boxes returned with the upload response that you
apply instead of measuring bounds yourself.
| Field | What it holds |
| ------------ | -------------------------------------------------------------------------- |
| `uuid` | The id of the preset. |
| `name` | Its label, such as `Full coverage` or `Centre logo`. |
| `size` | The `width` and `height` a design is drawn at. |
| `position` | Where the box sits on the smart object, as `x`, `y`, `width` and `height`. |
| `thumbnails` | Preview images of the preset. |
A preset is a marker on the artboard, not a division of it. It tells you where a
design is meant to sit; it does not cut the smart object into pieces.
## Learn more
Follow a product photograph from create call to finished render.
Address a design area inside a Photoshop template.
## Next steps
Place a design on a target and get a finished image.
Read the write contract and run it against your own mockup.