Read a blank
const url = 'https://api.pixonaut.app/v1/blanks/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.pixonaut.app/v1/blanks/example \ --header 'Authorization: Bearer <token>'Operation ID: blanks.get
One blank with its placements and variants. A deleted blank is read too, with when and by whom it was deleted, so an order placed on it can show it.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”The blank
object
The options the blank’s print areas change with, such as Size, in option order; empty for one print area per placement. Each placement’s areas names a row of these.
The blank’s option axes, such as Color and Size, in the order the shopper sees them. Empty for a blank with one variant.
The partner’s product a bound blank (partnerLocked) is bound to, or null for a blank bound to none. Answered for one blank, never in a list.
object
The partner’s own id of the product.
The product’s name as the printshop last reported it: at import, then at each check for printshop changes. Null when the record of the import is gone.
The blank this one was copied to its printshop from, or null.
object
The source blank’s id, which may since have been deleted.
The source blank’s name when it was copied.
When and by whom the blank was deleted, or null for a blank that is not. A deleted blank is read-only: restore it to change it.
object
When the blank was deleted, epoch ms.
The member who deleted it; null when a key did.
object
The member’s name as it is now; null once unknown.
The code a failed import failed with, such as partner_failed or storage_quota_exceeded; null unless status is failed.
The blank’s options with their values, in the order the shopper sees them, a value no variant uses yet included. axes is their names.
object
How each value looks to a shopper, by value: a colour fill, an image, or null for none. Every value of values is named.
object
The value is drawn in one or two flat colours.
object
One #rrggbb colour, or two for a heather or two-tone, drawn half and half.
Whether a product in this value is light or dark, set by you. Absent, a colour fill’s first colour decides (darker than mid grey is dark) and any other value is light. A template layer’s on-dark value is used on a dark one.
The value is drawn as a picture of it, such as a pattern.
object
An image in the workspace’s asset library.
Whether a product in this value is light or dark, set by you. Absent, a colour fill’s first colour decides (darker than mid grey is dark) and any other value is light. A template layer’s on-dark value is used on a dark one.
The option’s name per customer-facing language, by code: only the languages it has one in. A language left out reads name.
object
Each value’s name per customer-facing language, by value: only the values that have one. A language left out reads the value itself.
object
object
Whether a product in each value is light or dark, by value: the tone set on its appearance, else its colour fill’s, else light. Every value of values is named. On a variant of a dark value a template’s on-dark values are used.
object
When the blank’s options were confirmed: the merchant said it has one version, or added its first option. Null until then. A blank imported from a printshop’s catalogue arrives confirmed.
How many orders name the blank, past ones included. Answered in a list, never for one blank, and only to a caller with orders:read.
How much of the blank is photographed. Answered in a list.
object
The blank’s rows (each combination of the values of the options its photos change with; one for All) times its views.
The cells with a photo, of their own row or a covering one.
The options the blank’s photos change with, in option order: each photo belongs to one row, its values of these, and shows every variant with them. Empty is All: one photo per view shows every variant.
The blank’s placements: the areas a design is printed into. An update replaces the whole list, so send every placement to keep.
object
The placement’s print area per row of the blank’s areasVaryBy options, such as one per size; omitted or empty, the placement has one print area, its own. maxWidthMm and maxHeightMm are then the widest and tallest row, which every row fits inside.
object
Bleed past the trim on the row, in millimetres, 0 to 50. Omitted, the placement’s.
Print resolution on the row in dots per inch. Omitted, the placement’s.
The tallest print the row takes, in millimetres.
The row: a value for each areasVaryBy option, by option name. One area per row per placement.
object
Safe area inside the trim on the row, in millimetres, 0 to 50. Omitted, the placement’s.
The height a print gets on the row when none is chosen, in millimetres, at most heightMm.
The width a print gets on the row when none is chosen, in millimetres, at most widthMm.
The widest print the row takes, in millimetres.
Bleed past the trim on each side, in millimetres, 0 to 50. Omitted, its category’s, else the workspace’s.
How a print covers the placement: within, a print of any size up to the maximum placed inside it, or full, a print that is the whole area, such as an all-over-print panel. Omitted, within. A full placement’s usual size is its area, and a request naming a smaller size is refused print_size_not_area.
The height a print gets when none is chosen, in millimetres, at most maxHeightMm.
The width a print gets when none is chosen, in millimetres, at most maxWidthMm.
Print resolution in dots per inch. Omitted, its category’s, else 300.
The #rrggbb colour an optional placement left undesigned is printed or delivered as. Null or omitted for none.
Unique within the blank; a short stable one such as front, which a template refers to it by.
The placement it is linked with by default, such as a right sleeve with the left one: one design then drives both unless a designer link, an SDK mount or a design says otherwise. Null or omitted for none. A placement linked with one no longer on the blank is linked with none.
object
Whether this placement’s print is mirrored left to right when the two are linked.
The id of the blank’s other placement it is linked with by default.
The tallest print the placement takes, in millimetres.
The widest print the placement takes, in millimetres.
What it is called, such as Front or Back.
How this placement is printed, such as dtg or screen. Omitted, its category’s.
Whether an order on the blank must print it: one without a print for it is refused placement_unfilled. Omitted is false; a blank bound to its printshop’s product takes it from the printshop.
Safe area inside the trim on each side, in millimetres, 0 to 50. Omitted, its category’s, else the workspace’s.
Where on the product a print may go when that is not the whole rectangle: dFrac, SVG path data in fractions of the print area (curves, no arcs), its first subpath the outline and every further one a cut-out, filled even-odd, each subpath closed. Nothing is printed outside the outline or in a cut-out. cutByPrintShop true adds the outline and the cut-outs to the print file as its cut line; omitted, the product already has the shape. Null or omitted, the whole rectangle.
object
True when the print shop cuts the product to this shape: the outline and the cut-outs go into the print file as its cut line. Omitted, the product already has the shape.
The shape as SVG path data in fractions of the print area, 0 to 1 across and down (curves, no arcs): its first subpath the outline, every further one a cut-out, filled even-odd, each subpath closed.
Printed as: the name the blank’s printshop knows the placement by, on orders and job sheets. Null or omitted prints the placement’s name.
The ways the placement is photographed, such as Flat or On model. Every photo of one view shares its pixel size and its print area.
object
True on a view a blank bound to its printshop’s product took from the printshop (its import, Add colours, model photos): its photo size and print area are the printshop’s and cannot change by hand. Absent on a view the workspace added. Set only by the printshop’s own paths; a save that sends it is ignored.
Unique within the blank.
What it is called, such as Flat or On model; unique within its placement, ignoring case.
What it is called per customer-facing language, by code: only the languages it has a name in; a language left out reads label. No two views of its placement read the same in one language, ignoring case.
object
A library asset of the view’s photo size: where it is light the print shows, where it is dark the print is hidden, as behind a sleeve or a fold. Absent hides nothing.
Control points the print is laid through or, marked cut, cut to, rows from its top edge and points from its left, as [x, y] in the photo’s original pixels; at least 2 and at most 33 along each side. Absent, the print is laid in the rect.
object
The points draw a shape to cut the print to (CONTEXT.md → Region cut) rather than a mesh to bend it through: the print is laid flat over the box the points span, at its own proportions and filling it, and everything outside the shape the outer points draw is cut away. Absent, the print is warped through the mesh.
The rows of control points, from the print’s top edge.
The printshop’s own key for the photo style the view was made from, such as a model or lifestyle style; absent on a view made by hand or imported with the product.
The pixel size every photo of the view has; null until the view holds a photo.
object
The photo’s height, in pixels.
The photo’s width, in pixels.
The view’s product photos, each the same size as the view.
object
The photo’s asset id, as the assets feature returns it after an upload.
How far the photo’s folds move the design, more than 0 and at most 1. null moves nothing. Omitted, its category’s, else nothing.
The photo’s id, unique within the blank: the mockupId a render and a mockup link name.
The photo’s value of each photosVaryBy option; empty when there are none. One photo per row per view.
object
How strongly the photo’s light and shade carry onto the design, 0 (none) to 1 (all). Omitted, its category’s, else the default strength.
How strongly the photo’s fine detail, such as a weave or a grain, shows through the print, 0 (none) to 1 (all). Omitted, its category’s, else, as for null, the default strength.
The variants the photo shows, from its row. A write may name the row by these instead.
object
How far round the product the design wraps, more than 0 and at most 1. Flat is a null warp, not 0.
How much the design darkens toward the product’s sides, 0 (none) to 1 (black at the edge). Omitted, none.
The kind of wrap; cylinder is the only one.
A pattern piece of the view’s UV pass, 1 to 254: the region’s print is read through the pixels the pass marks with it, in place of a mesh.
Where the print area sits on every photo of the view, in the original photo’s pixels; null until it is marked.
object
The print area’s height, in pixels.
The print area’s width, in pixels.
The print area’s left edge, in pixels from the photo’s left.
The print area’s top edge, in pixels from the photo’s top.
The part of the region’s piece its print covers, in millimetres on the piece’s unwrapped surface from its top-left corner, such as a square on the side of a cup: the print is read inside it, at the window’s size, and the product shows plain outside it. It lies inside its piece, and needs the piece’s size on the view. Absent, the print covers the whole piece.
object
The window’s height, in mm.
The window’s width, in mm.
The window’s left edge, in mm from the piece’s left.
The window’s top edge, in mm from the piece’s top.
The piece of the placement’s print the region shows, in millimetres from the print’s top-left corner, such as a roll’s window; clamped to the print when the print is smaller. Absent, the region shows the whole print at the size of the render’s variant.
object
The window’s height, in mm.
The window’s width, in mm.
The window’s left edge, in mm from the print’s left.
The window’s top edge, in mm from the print’s top.
The maps the view was rendered with from a 3D model of the product, each the view’s photo size; a region naming a piece is drawn through them. Absent, the view’s regions are laid in their rect or mesh.
object
The multiply pass: the garment’s shadows and folds.
Each piece’s print size on the model, as its view.json gives it: what a region’s print window is placed on. Absent, no region of the view may name a print window.
A piece of the UV pass and its print’s size on the model.
object
The piece’s print height on the model, in mm.
A pattern piece of the view’s UV pass, 1 to 254: the region’s print is read through the pixels the pass marks with it, in place of a mesh.
The piece’s print width on the model, in mm.
The pieces the UV pass marks, as its view.json lists them.
The screen pass: the garment’s highlights.
The 16-bit UV pass: for each pixel, its piece (blue) and where across (red) and down (green) that piece’s print it reads.
The placements printed as a position that prints one size only at the blank’s printshop whose default print size is another size: flagged, never refused, since an order of the position’s size is still taken. Answered for one blank, never in a list.
object
The printshop’s position the placement is printed as.
The one size that position prints, in mm.
object
The row a design that names none is made at, such as {“Size”: “M”}; null for none, when such a design reads each placement’s own print area. Required when the print areas start to change with an option on a blank that has designs or designer links, which keep their size at it.
Each inheritable field resolved, with where it comes from: the printshop and machine, and every placement’s and photo’s printing fields and preview looks, in the order of placements.
object
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
The placement’s photos, every view’s in view order.
object
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
object
How far round the product the design wraps, more than 0 and at most 1. Flat is a null warp, not 0.
How much the design darkens toward the product’s sides, 0 (none) to 1 (black at the edge). Omitted, none.
The kind of wrap; cylinder is the only one.
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
Printed as: the name the blank’s printshop knows the placement by, on orders and job sheets. The placement’s own shopName, else its name.
Whether Printed as follows the placement’s name: true while it has no shopName of its own.
object
Where the value comes from: the field’s own, its blank category’s, the workspace’s default, or none (nothing sets it, and the built-in default applies).
The first photo of the blank’s first view of several placements that has one, in their order: the view, the photo (a mockup), its asset and the view’s photo size. A blank whose views of one placement have no photo is pictured by it. Null for a blank with no such photo. Answered in a list.
object
object
The photo’s height, in pixels.
The photo’s width, in pixels.
importing while the blank’s import, from a printshop’s catalogue or a CSV file, runs in the background: it has its name and nothing else yet. failed when that import failed for good (importFailure says why); remove it and import again. ready otherwise.
A link to the blank’s picture, opening with no key for an hour or two, so a list shows a picture of each blank: its first photo of a view of one placement, else sharedViewPhoto. Null for a blank with no photo. Answered in a list.
How many variants the blank has, deleted ones included. Answered in a list.
The blank’s variants, retired ones included, with their printshop fields. Answered for one blank, never in a list.
Examples
Example
{ "areasVaryBy": [], "axes": [], "boundProduct": null, "categoryId": "bcat_tees", "copiedFrom": null, "createdAt": 1760000000000, "defaultPrintshopId": "ps_default", "deleted": null, "id": "blank_tshirt", "importFailure": null, "machineProfileId": null, "name": "Classic T-shirt", "options": [], "optionsConfirmedAt": 1790000300000, "partnerLocked": false, "photosVaryBy": [], "placements": [ { "bleedMm": 3, "defaultHeightMm": 360, "defaultWidthMm": 280, "id": "front", "maxHeightMm": 360, "maxWidthMm": 280, "name": "Front", "printMethod": "dtg", "views": [ { "id": "view-front-flat", "label": "Front, flat lay", "photoSizePx": { "heightPx": 1500, "widthPx": 1200 }, "photos": [ { "assetId": "asset_front_flat", "id": "mock-front", "row": {} } ], "placementRectPx": { "h": 488, "w": 380, "x": 410, "y": 360 } } ] } ], "referenceRow": null, "resolved": { "defaultPrintshopId": { "source": "own", "value": "ps_default" }, "machineProfileId": { "source": "none", "value": null }, "placements": [ { "bleedMm": { "source": "own", "value": 3 }, "dpi": { "source": "category", "value": 300 }, "id": "front", "mockups": [ { "displacementStrength": { "source": "none", "value": null }, "id": "mock-front", "shadingStrength": { "source": "none", "value": null }, "textureStrength": { "source": "none", "value": null }, "warp": { "source": "none", "value": null } } ], "printMethod": { "source": "own", "value": "dtg" }, "printedAs": "Front", "printedAsLinked": true, "safeAreaMm": { "source": "workspace", "value": 3 } } ] }, "status": "ready", "updatedAt": 1760000000000}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, forbidden, feature_disabled, 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: 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].