Check a customer's payload against its template
const url = 'https://api.pixonaut.app/v1/validate?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/validate?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: payloads.validate
Validates the values a customer gave a published template, and the placement and print size the request names, without rendering or storing anything. A named placement that does not resolve is refused with unknown_placement. On a blank whose print areas change with its size, the payload is judged at the size its variant or variantRow names, or at the blank’s reference row when it names neither.
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.
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.
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 payload is valid; the hash of the document it resolves to
object
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", "lowResolution": [], "ok": true, "printFloorDpi": 150}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, payload_too_large
object
Sent with payload_too_large.
Always sent with 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
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
object
Examples
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.
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.
Questions? Write to [email protected].