Commit a design drawn on a blank's panel layout

POST

/v1/designs/layout

const url = 'https://api.pixonaut.app/v1/designs/layout';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"blankId":"blk_3f9a2c1d8e7b6a5f4c3d2e1f","layout":"All-over","templateId":"pug-fur@2","values":{},"variantRow":{"Size":"L"}}'
};

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/designs/layout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "blankId": "blk_3f9a2c1d8e7b6a5f4c3d2e1f", "layout": "All-over", "templateId": "pug-fur@2", "values": {}, "variantRow": { "Size": "L" } }'

Operation ID: designs.commitThroughLayout

Commits a design drawn across a blank’s panel layout, so all-over art runs unbroken across the seams of the panels it is printed on. The template is resolved once, on the layout’s canvas at the size the request names (variant or variantRow, as on POST /v1/designs), and the answer holds one design per placement the layout has a window for: its print is the canvas seen through that placement’s windows, the size of the placement’s print area at that size. Order them as the prints of one item. In place of a template and its values, a secret or integration key may send the proofToken of a layout’s proof the customer approved (POST /v1/proofs/layout): its canvas is cut as approved, at the proof’s blank, layout and size, and the token commits once. A proof of anything else is refused not_layout_proof. A layout the blank does not have is refused unknown_layout; one whose windows no longer fit the blank’s print areas at that size, layout_out_of_date. Every design is resolved and checked before any is made; one refused after that leaves the others made. A secret key, an integration key with designs:create, or a member.

Authorizations

Request Body^required

application/json

Any of:

object
object

object

externalRef

The caller’s own reference, kept on every design made.

string

>= 1 characters <= 200 characters

proofToken

required

The token of the layout’s proof the customer approved (POST /v1/proofs/layout): its canvas is cut as approved, at its blank, layout and size. A secret or integration key only.

string

>= 1 characters

object

blankId

required

string

>= 1 characters

externalRef

The caller’s own reference, kept on every design made.

string

>= 1 characters <= 200 characters

garmentVariant

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.

string

>= 3 characters <= 100 characters

layout

required

The name of the blank’s panel layout the design is drawn on.

string

>= 1 characters

repeat

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

mode

required

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.

string

Allowed values: grid brick halfDrop scatter

seed

required

Which arrangement a scatter draws: another seed is another arrangement of the same tile. Read by scatter only.

integer

<= 9007199254740991

size

required

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.

number

> 0 <= 100

templateId

required

The published template version, <baseId>@<version>.

string

>= 1 characters

values

The customer’s values, as on POST /v1/designs.

object

key

additional properties

variant

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.

string

>= 3 characters <= 100 characters

variantRow

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

key

additional properties

string

>= 1 characters <= 80 characters

Examples

example

Example

{
  "blankId": "blk_3f9a2c1d8e7b6a5f4c3d2e1f",
  "layout": "All-over",
  "templateId": "pug-fur@2",
  "values": {},
  "variantRow": {
    "Size": "L"
  }
}

Responses

201

The designs made

application/json

object

designs

required

One design per placement the layout has a window for, in the order of the layout’s windows; the first is the lead.

Array<object>

object

designId

required

string

heightMm

required

The print’s trim height, in millimetres.

number

placementId

required

string

widthMm

required

The print’s trim width, in millimetres.

number

lowResolution

required

The pictures that print below printFloorDpi at the design’s print size. A warning: nothing is refused for it.

Array<object>

object

actualPx

required

The picture’s pixels along the edge that decides.

number

assetId

required

string

effectiveDpi

required

Pixels per inch along that edge, as printed.

number

layerId

required

The layer the picture fills, or the artwork’s own key for its image background.

string

minPx

required

The pixels that edge needs at the floor.

number

printFloorDpi

required

The minimum print resolution the design’s pictures were judged against: the template’s own, else the tenant’s.

number

Examples

example

Example

{
  "designs": [
    {
      "designId": "6f1c8a2b-3d4e-4f5a-8b6c-7d8e9f0a1b2c",
      "heightMm": 720,
      "placementId": "front",
      "widthMm": 560
    },
    {
      "designId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "heightMm": 420,
      "placementId": "hood",
      "widthMm": 660
    }
  ],
  "lowResolution": [],
  "printFloorDpi": 150
}

Headers

X-Request-Id

required

string

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.

400

Refused: bad_request

application/json

object

error

required

string

Examples

bad_request

{
  "error": "bad_request"
}

Headers

X-Request-Id

required

string

401

Refused: unauthorized

application/json

object

error

required

string

Examples

unauthorized

{
  "error": "unauthorized"
}

Headers

X-Request-Id

required

string

403

Refused: secret_key_required, forbidden, origin_forbidden, feature_disabled, workspace_suspended

application/json

object

error

required

string

feature

The feature the tenant does not have. Always sent with feature_disabled.

string

Examples

feature_disabled

{
  "error": "feature_disabled",
  "feature": "api"
}

forbidden

{
  "error": "forbidden"
}

origin_forbidden

{
  "error": "origin_forbidden"
}

secret_key_required

{
  "error": "secret_key_required"
}

workspace_suspended

{
  "error": "workspace_suspended"
}

Headers

X-Request-Id

required

string

404

Refused: unknown_proof, not_found

application/json

object

error

required

string

Examples

not_found

{
  "error": "not_found"
}

unknown_proof

{
  "error": "unknown_proof"
}

Headers

X-Request-Id

required

string

409

Refused: layout_out_of_date, proof_already_committed, not_layout_proof

application/json

object

designId

Always sent with proof_already_committed.

string

error

required

string

reason

Always sent with layout_out_of_date.

string

Examples

layout_out_of_date

{
  "error": "layout_out_of_date",
  "reason": "string"
}

not_layout_proof

{
  "error": "not_layout_proof"
}

proof_already_committed

{
  "designId": "string",
  "error": "proof_already_committed"
}

Headers

X-Request-Id

required

string

410

Refused: proof_expired

application/json

object

error

required

string

Examples

proof_expired

{
  "error": "proof_expired"
}

Headers

X-Request-Id

required

string

422

Refused: unknown_printshop, printshop_disconnected, printshop_unavailable, printshop_differs_from_blank, constraint_violation, unknown_placement, variant_not_of_blank, variant_row_invalid, variant_required, spot_plate_required, asset_map_too_large, unknown_layout, empty_layout, invalid_doc, payload_too_large

application/json

object

areasVaryBy

Always sent with variant_required.

Array<string>

bytes

Always sent with asset_map_too_large, and may be sent with payload_too_large.

number

cause

Always sent with spot_plate_required.

string

detail

Always sent with invalid_doc.

error

required

string

maxBytes

Always sent with asset_map_too_large, payload_too_large.

number

reason

Always sent with unknown_printshop, printshop_disconnected, printshop_unavailable, printshop_differs_from_blank, variant_not_of_blank, variant_row_invalid, variant_required.

string

references

Always sent with spot_plate_required.

Array<string>

variant

Always sent with variant_not_of_blank.

string

violations

Always sent with constraint_violation.

Array<object>

object

characters

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.

Array<string>

given

required

language

The language whose overrides break the rule, when only the template as it reads in that language does. Absent, the original.

string

layerId

required

string

prop

required

string

rule

required

string

severity

required

error refuses a publish; warning is worth the author’s attention and never does.

string

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"
    }
  ]
}

empty_layout

{
  "error": "empty_layout"
}

invalid_doc

{
  "detail": {},
  "error": "invalid_doc"
}

payload_too_large

{
  "error": "payload_too_large",
  "maxBytes": 0
}

printshop_differs_from_blank

{
  "error": "printshop_differs_from_blank",
  "reason": "string"
}

printshop_disconnected

{
  "error": "printshop_disconnected",
  "reason": "string"
}

printshop_unavailable

{
  "error": "printshop_unavailable",
  "reason": "string"
}

spot_plate_required

{
  "cause": "printshop_takes_no_plates",
  "error": "spot_plate_required",
  "references": [
    "string"
  ]
}

unknown_layout

{
  "error": "unknown_layout"
}

unknown_placement

{
  "error": "unknown_placement"
}

unknown_printshop

{
  "error": "unknown_printshop",
  "reason": "string"
}

variant_not_of_blank

{
  "error": "variant_not_of_blank",
  "reason": "string",
  "variant": "string"
}

variant_required

{
  "areasVaryBy": [
    "string"
  ],
  "error": "variant_required",
  "reason": "string"
}

variant_row_invalid

{
  "error": "variant_row_invalid",
  "reason": "string"
}

Headers

X-Request-Id

required

string

429

Refused: rate_limited, link_design_limit

application/json

object

error

required

string

reopensAt

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.

number | null

Examples

link_design_limit

{
  "error": "link_design_limit",
  "reopensAt": 0
}

rate_limited

{
  "error": "rate_limited"
}

Headers

X-Request-Id

required

string

500

Refused: db_error. A request that failed unexpectedly answers as text instead.

object

error

required

string

Examples

db_error

{
  "error": "db_error"
}

Headers

X-Request-Id

required

string

Questions? Write to [email protected].

Status · Terms of service · Privacy policy · Subprocessors

Commit a design drawn on a blank's panel layout

Authorizations

Request Bodyrequired

Examples

Responses

201

Examples

Headers

400

Examples

Headers

401

Examples

Headers

403

Examples

Headers

404

Examples

Headers

409

Examples

Headers

410

Examples

Headers

422

Examples

Headers

429

Examples

Headers

500

Examples

Headers

Request Body^required