Render a proof
const url = 'https://api.pixonaut.app/v1/proofs?lang=en';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"blankId":"blank_tshirt","heightMm":300,"placementId":"front","templateId":"tshirt-basic@2","values":{"headline":{"content":"Class of 2026"}},"widthMm":250}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.pixonaut.app/v1/proofs?lang=en' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "blankId": "blank_tshirt", "heightMm": 300, "placementId": "front", "templateId": "tshirt-basic@2", "values": { "headline": { "content": "Class of 2026" } }, "widthMm": 250 }'Operation ID: proofs.create
Validates a customer’s payload as POST /v1/validate does, renders the proof image a customer approves, and answers with a signed link to it. The proof is fitted to the placement the request names, and the proof token commits the design later with that blank and placement. On a blank whose print areas change with its size, it is fitted to the size its variant or variantRow names, or to the blank’s reference row when it names neither, and a token of a proof that named none is refused variant_required at commit.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The IANA timezone the template’s dynamic values are resolved in, such as Europe/Stockholm: today’s date there. Absent, the workspace’s timezone.
The IANA timezone the template’s dynamic values are resolved in, such as Europe/Stockholm: today’s date there. Absent, the workspace’s timezone.
The language the template’s dynamic values are written in when their name names none, one of en, sv, de, fr, es, nl, da, nb, fi. Absent, the workspace’s default language. A value whose name carries a language, {date.long:sv}, keeps it.
The language the template’s dynamic values are written in when their name names none, one of en, sv, de, fr, es, nl, da, nb, fi. Absent, the workspace’s default language. A value whose name carries a language, {date.long:sv}, keeps it.
Header Parameters
Section titled “Header Parameters”The designer’s browser session, which the SDK sends so one visitor’s uploads and proofs are told apart from another’s on the same key: 6 to 64 letters, digits, _ or -. Any other value is ignored.
The designer’s browser session, which the SDK sends so one visitor’s uploads and proofs are told apart from another’s on the same key: 6 to 64 letters, digits, _ or -. Any other value is ignored.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The id of a published template.
The customer’s values for the template’s fields.
The linked group the placement is designed as part of: every placement one design drives, this one among them, each with whether its print is mirrored. The print is mirrored when this placement’s entry says so, and a repeat on it is laid at one physical scale across the group: the document records the group and the width of its widest placement’s print area (linked.referenceWidthMm). Needs blankId and placementId; each placement must be one of the blank’s.
object
Placements one design drives, two at least.
object
Whether the placement’s print is mirrored left to right.
The id of one of the blank’s placements.
Whether the designer drew the customer’s canvas at the template’s own ratio, as the SDK mount option of that name sets it. The design is made at the chosen size through the template’s fit either way, so this changes nothing in what is made.
A variant of the blank, by ref (v_…). On a blank whose print areas change with its size, the design is sized at, and keeps, that variant’s size; a ref the blank has no variant of is refused with variant_not_of_blank. On any other blank it is not checked. A proof also keeps it as proofVariant, for display.
The size the design is for, as the blank’s option values, such as {"Size": "XL"}, in place of variant: a value of each option the blank’s print areas change with, and nothing else, or it is refused with variant_row_invalid. Ignored on a blank whose print areas change with nothing.
object
The variant whose colour the design is drawn in, by ref (v_…), when it is not the one variant names: on a dark colour each layer takes its on-dark value. It sizes nothing. A proof keeps it as proofVariant, so its commit is drawn in the same colour. Absent, variant’s colour; a ref the blank has no variant of draws as on a light product.
Lays the design as a repeat of its template across the print area. Null, or absent, places it once. Through a designer link, a repeat the link offers, or null where its shopper may turn the repeat off; absent there, the link’s own start.
object
How the tiles are laid: grid lines them up, brick moves every other row along by half a tile, halfDrop moves every other column down by half a tile, and scatter strews them at random places, turns and sizes, arranged by seed.
Which arrangement a scatter draws: another seed is another arrangement of the same tile. Read by scatter only.
The tile’s width in percent of the print area’s width, above 0 and at most 100; the tile keeps the template’s shape. A tile that would print under 10 mm on a side is drawn at 10 mm.
The view of the blank’s placement the customer previewed the proof in, by id. Kept with the proof and read with the design’s proof as proofViewId, for display only.
Examples
Example
{ "blankId": "blank_tshirt", "heightMm": 300, "placementId": "front", "templateId": "tshirt-basic@2", "values": { "headline": { "content": "Class of 2026" } }, "widthMm": 250}Responses
Section titled “Responses”The proof, its image link and its token
object
When the proof and its token expire, in milliseconds since the Unix epoch.
The pictures that print below printFloorDpi at the design’s print size. A warning: nothing is refused for it.
object
The picture’s pixels along the edge that decides.
Pixels per inch along that edge, as printed.
The layer the picture fills, or the artwork’s own key for its image background.
The pixels that edge needs at the floor.
The minimum print resolution the design’s pictures were judged against: the template’s own, else the tenant’s.
Examples
Example
{ "docHash": "sha256:9f2c4e7a1b8d3f6052c7e9a4b1d8f3066a5e2c9b7d4f1830e6a2b5c8d9f10a37", "expiresAt": 1792491247000, "lowResolution": [], "printFloorDpi": 150, "proofToken": "eyJhdWQiOiJwcm9vZiIsImlkIjoicHJmXzljMWUyZDNmNGE1YjZjN2Q4ZTlmMGExYiIsInQiOiJhY21lIiwiZXhwIjoxNzkyNDkxMjQ3MDAwfQ.EXAMPLE_signature_not_a_real_one_0000000000", "proofUrl": "https://api.pixonaut.example/p/eyJhdWQiOiJwcm9vZiIsImlkIjoicHJmXzljMWUyZDNmNGE1YjZjN2Q4ZTlmMGExYiIsInQiOiJhY21lIiwiZXhwIjoxNzkyNDkxMjQ3MDAwfQ.EXAMPLE_signature_not_a_real_one_0000000000"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: bad_json, bad_request, invalid_query
object
Always sent with invalid_query.
Examples
bad_json
{ "error": "bad_json"}bad_request
{ "error": "bad_request"}invalid_query
{ "error": "invalid_query", "reason": "string"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: unauthorized
object
Examples
unauthorized
{ "error": "unauthorized"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: origin_forbidden, feature_disabled, forbidden, workspace_suspended
object
The feature the tenant does not have. Always sent with feature_disabled.
Examples
feature_disabled
{ "error": "feature_disabled", "feature": "api"}forbidden
{ "error": "forbidden"}origin_forbidden
{ "error": "origin_forbidden"}workspace_suspended
{ "error": "workspace_suspended"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: not_found
object
Examples
not_found
{ "error": "not_found"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: constraint_violation, unknown_placement, variant_not_of_blank, variant_row_invalid, asset_map_too_large, payload_too_large
object
Always sent with asset_map_too_large, and may be sent with payload_too_large.
Always sent with asset_map_too_large, payload_too_large.
Always sent with variant_not_of_blank, variant_row_invalid.
Always sent with variant_not_of_blank.
Always sent with constraint_violation.
object
On a text_draws_fallback_glyphs or text_draws_missing_glyphs warning: the characters the text’s font cannot draw, each once, in the order the text first holds them. Absent on every other violation.
The language whose overrides break the rule, when only the template as it reads in that language does. Absent, the original.
error refuses a publish; warning is worth the author’s attention and never does.
Examples
asset_map_too_large
{ "bytes": 0, "error": "asset_map_too_large", "maxBytes": 0}constraint_violation
{ "error": "constraint_violation", "violations": [ { "given": {}, "layerId": "string", "prop": "string", "rule": "string", "severity": "error" } ]}payload_too_large
{ "error": "payload_too_large", "maxBytes": 0}unknown_placement
{ "error": "unknown_placement"}variant_not_of_blank
{ "error": "variant_not_of_blank", "reason": "string", "variant": "string"}variant_row_invalid
{ "error": "variant_row_invalid", "reason": "string"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: rate_limited, link_design_limit
object
When the link makes designs again: when the oldest design counted leaves the window. Null for a total limit. Always sent with link_design_limit.
Examples
link_design_limit
{ "error": "link_design_limit", "reopensAt": 0}rate_limited
{ "error": "rate_limited"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
The caller left before the render started
object
Examples
client_closed_request
{ "error": "client_closed_request"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: db_error. A request that failed unexpectedly answers as text instead.
object
Examples
db_error
{ "error": "db_error"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: assets_unavailable
object
Examples
assets_unavailable
{ "error": "assets_unavailable"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Questions? Write to [email protected].