Skip to content
Docs
Sign in

Imposition API

Create imposition jobs, add artwork, run the nest, read the layouts and download the imposed PDF, cut files and method exports.

For integrators

The imposition API does everything the workspace does: jobs, artwork, runs, layouts and exports. What the workspace calls a solution (one complete plan: every sheet or form it uses) is a layout in the API, so a saved solution is a layout under /layouts/. Every endpoint is under your team, starting with /a/{team_slug}/imposition-layout/api/v1/jobs/, and takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session (see API overview).

All lengths are in points (1/72 in), whatever unit the job displays.

A job from start to finish#

JOBS=https://app.example.com/a/acme/imposition-layout/api/v1/jobs/
AUTH="Authorization: Api-Key $API_KEY"

# 1. Create a job: 12 x 18 in sheets, N-up, digital (the answer has its id, here 42)
curl -s -X POST "$JOBS" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Postcards", "sheet_width": 864, "sheet_height": 1296, "method": "guillotine"}'

# 2. Upload artwork to job 42
curl -s -X POST "${JOBS}42/artworks/" -H "$AUTH" \
  -F file=@postcard-a.pdf -F quantity=500 -F rotation_preset=0_90

# 3. Start a run with a 20 s budget, then poll it until the status is completed
curl -s -X POST "${JOBS}42/run/" -H "$AUTH" -H "Content-Type: application/json" -d '{"time_limit_s": 20}'
curl -s "${JOBS}42/run/" -H "$AUTH"

# 4. Download the best layout (its ref comes from the run state's candidates)
curl -s -o imposed.pdf "${JOBS}42/layouts/c-0123456789ab/imposed-pdf/" -H "$AUTH"
curl -s -o cut.dxf "${JOBS}42/layouts/c-0123456789ab/cutfile/?format=dxf" -H "$AUTH"

Jobs#

GET /a/{team_slug}/imposition-layout/api/v1/jobs/

Find jobs by order number: [{id, name, external_id, customer_name, reference, due_at, priority, status, updated_at, url}], newest first.

imposition_jobs_list · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/

imposition_jobs_create · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/

imposition_jobs_retrieve · View in API reference

PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/

imposition_jobs_partial_update · View in API reference

DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/

imposition_jobs_destroy · View in API reference

A job has these writable fields. Lengths are points; the ranges are the ones the API accepts.

FieldIn the appRange or valuesMeaning
nameJob name–The job's name, shown in the job list and in export file names.
descriptionDescription–A short note under the name.
display_unitUnitin, pt, mm, cmThe unit the workspace shows lengths in. The API always uses points.
media_typeMedia typesheet, rollSheet or Roll.
sheet_widthWidth36 to 14400Sheet width.
sheet_heightHeight36 to 14400Sheet height.
roll_widthRoll width36 to 14400Roll width. Switching to a roll starts from the sheet width.
margin_topTop0 to 720Sheet margin at the top: nothing is placed there.
margin_bottomBottom0 to 720Sheet margin at the bottom.
margin_leftLeft0 to 720Left margin (on a roll: the left side margin).
margin_rightRight0 to 720Right margin (on a roll: the right side margin).
lead_inLead-in0 to 8640Roll: blank length before the first piece.
lead_outLead-out0 to 8640Roll: blank length after the last piece.
gutterSpacing0 to 720The gap the nest keeps between pieces (between their bleed edges).
bleedBleed0 to 144The bleed of artworks whose Bleed is None (job default).
media_grainMedia grainnone, horizontal, verticalThe grain of the stock: none, horizontal or vertical.
rotation_presetDefault rotationnone, 0_180, 0_90, quarter, anyThe rotation of artworks set to Job default.
time_limit_sTime1 to 600How long you are willing to let the run search, in seconds.
max_sheetsMax sheets0 to 500The most sheets a digital sheet run may use. 0 = unlimited.
shape_paddingContour padding0 to 144Pixel contour shapes: grows the traced outline.
shape_marginContour margin0 to 144Pixel contour shapes: grows the traced outline further.
bed_policyBed boundaries"", within, spanRoll jobs: empty (the cutter's setting), within or span.
methodMethodauto, free, guillotine, stripsauto, free (True shape), guillotine (N-up) or strips.
run_typeRun typedigital, offsetdigital or offset.
method_settingsSettings…–The method settings: an object with guillotine and strips sections.
max_platesMax forms1 to 99Offset: the most forms (plate sets) a plan may use, 1 to 99; null: Auto. The name is historical.
overrun_pctOverrun %0 to 500Offset: the overrun cap per item; null = any.
underrun_pctUnderrun %0 to 50Offset: the underrun allowance per item.
makeready_sheetsMakeready sheets0 to 10000Offset: setup sheets per form.
spoilage_pctSpoilage %0 to 50Offset: waste added to every form's sheets.
form_extra_costExtra cost per form–Offset: money added once per form on top of the plates (proofs, a share of a die), a decimal string; null = none.
plate_set_costPlate set cost (per form)–Offset: the cost of one form's plate set (a decimal string), used only when no platemaker and no press plate cost prices the plates; null = none.
plate_costPlate cost (deprecated)–Write-only, deprecated: the old single field. A written value goes to form_extra_cost when the job's offset press has a plate cost, else to plate_set_cost. Never returned.
machineCutter–A cutting machine id; null uses the team default.
printerPrinter–A printer id; null uses the team default.
print_modePrint mode–One of the printer's modes; empty uses its default mode.
printedPrinted–Off for jobs that are only cut (no print time).
sheet_costSheet cost (per sheet)–The cost of one sheet (a decimal string).
roll_cost_per_sq_ftRoll cost (per sq ft)–The media cost of a roll job (a decimal string).
split_itemsSplit items across formsallow, avoid, neverallow, avoid or never: whether an item's copies may be spread over several forms or plates. avoid splits only when that saves more than the minimum saving.
split_min_saving_pctMinimum saving to split (%)–With avoid: the saving a split plan must beat.
gangingGanging rules–This job's additions to the team's ganging rules (Match on, Keep apart and so on); null uses the team's rules as they are. A job can add to the team's rules but not remove them.
pressPress–A press id for sheet work (offset or digital cut-sheet); null uses the team default.
ink_limitInk limitauto, off, warn, fit, passesauto, off, warn, fit or passes: how offset forms keep to the press's printing units. auto fits the press on offset and only warns on digital.
work_styleWork styleauto, single, sheetwise, perfecting, work_and_turn, work_and_tumbleauto, single, sheetwise or perfecting: how the back of a double-sided item is printed. work_and_turn and work_and_tumble are refused for now.
back_flipBack flipauto, turn, tumbleauto, turn or tumble: how the sheet is turned over for the backs of two-sided items, which decides where each back lands on the imposed PDF's back pages (auto: tumble on a perfecting job, else turn).
customer_nameCustomer–The customer's name, used by ganging rules, marks and scheduling.
due_atDue–When the job is due, as an ISO 8601 date-time. An item can have its own due in its properties.
priorityPriority1, 2, 3, 41 Rush, 2 High, 3 Normal (the default) or 4 Low.
external_idOrder number–Your system's id for the order, unique in the team (409 with existing_id when taken); marks print it.
referenceReference (PO)–The customer's PO or reference, up to 100 characters.
metadataOrder fields–Your own order fields for marks, a JSON object of at most 64 KB; merge-patch it with jobs/{id}/metadata/.
label_settingsLabel lanes–Labels on a roll, or null: width, height (the label on the web, pt), across, gap_across, gap_around, frame (max, endless or repeat) with frame_length, repeat_rows, lane_changes, changeover, separators, fill (blank or overs), per_roll or max_diameter, core, caliper, rewind (1 to 8) and rewinds (1 or 2).
die_policyDie policynone, compare, standing, newOffset: none (plan freely), compare, standing or new; null = the team's default (compare when a die on hand fits an item exactly). Jobs made before dies existed are none.
toolDie–A die (tool id) the job must use under standing; null tries every die that fits.
die_cutterDie-cutter–A die-cutter (finishing machine id); null uses the team's only one, if any.
die_settingsTooling settings–An object: new_ups (extra new-die ups to try), amortise_orders (spread a new die over N orders, ranking only), fill_blank, rush, die_to_sheet [x, y, angle] mm and quoted_tool; a null key uses the team's.

method_settings holds the method's settings as {"guillotine": {…}, "strips": {…}} (see Settings reference). A job read also returns method_resolved (what Auto becomes), the cutter and printer it resolves to, input_hash, fresh (whether the last run is current) and a light run state.

On a roll, guillotine and offset are refused ("N-up needs sheets.", "Offset runs need sheets."), and switching an existing job to a roll moves them to auto and digital.

Offset jobs keep two per-form costs: form_extra_cost (always added once per form) and plate_set_cost (used only when no platemaker and no press plate cost prices the plates). A read also returns plate_source, {"kind", "label", "platemaker_name"}, where kind is platemaker, press, job_form or unpriced: where the job's plate money comes from (see Offset press runs). max_plates is Max forms in the app: the most forms (plate sets) a plan may use, from 1 to 99, or null for Auto (every count up to one form per item; new jobs start on Auto).

When artworks name a library material, a read also returns material_media: {"materials": [{"id", "name"}], "decided_by": [names], "fields": [job fields], "problem": text or null}, or null while no artwork has one. fields lists the job fields the materials set (media_type, the sheet size or roll width, a roll's margins and lead-in / lead-out, sheet_cost or roll_cost_per_sq_ft); a PATCH that changes one of them is refused (400) until the artworks' material is cleared. problem says why the materials can't run together (different sizes or forms). See Item properties.

Warning: Deprecated: plate_cost

The single plate_cost field was split into form_extra_cost and plate_set_cost. For one release a written plate_cost is still accepted: it goes to form_extra_cost when the job's offset press has a plate cost, else to plate_set_cost (a field sent in the same request wins). Reads no longer return it.

Label lanes#

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/

LabelLanesJSON: the job's label settings (defaults filled in), the artwork's turn on the web (angle), the items that don't fit the label at that turn (warnings) and the lane plan (rows, frames, length, lanes, frame runs, rolls, items, problems) and the label press's estimate of the run (frames, clicks, web, time, cost and price; null without a label press).

imposition_jobs_labels · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/frames-pdf/

The frames PDF: one page per frame run (the run list gives each page's copies), or every frame.

imposition_jobs_labels_frames_pdf · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/run-list/

The run list: per page of the frames PDF, its frames, copies and what each lane holds.

imposition_jobs_labels_run_list · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/rolls/

The roll list: each lane's finished rolls with labels, length and diameter in the job's unit.

imposition_jobs_labels_rolls · View in API reference

A roll job with label_settings is a label job. GET …/labels/ answers {settings, angle, warnings, plan, estimate}: the settings with their defaults, the artwork's turn on the web for the wind position, the items too large for the label at that turn, and the plan: rows, rows_per_frame, frames, length (pt), blanks, per_roll, lanes (per lane, segments of {item, start, rows, overs, before}; item null is a changeover, which names the next item in before, or blank labels), runs (one per page of the frames PDF: {page, first, copies, lanes}), rolls ({lane, item, number, of, labels, length, diameter}), items ({item, name, quantity, made}) and problems ({code, detail}). labels/frames-pdf/ refuses a plan with problems (409); with ?expand=1 it has one page per frame. A PDF of more than 100,000 label cells (pages × rows in a frame × lanes) answers 400 too_many_labels. A plan of more than 20,000 rolls has the problem too_many_rolls. A job without label settings answers 404 not_a_label_job. See Label lanes: frames, lane changes and rolls. The settings' separations (1–20, default 4) and specials (white or special hits among them) price the run on the job's label press (its press when that is a label press, else the team's default): estimate is null without one, else {press: {id, name, charge}, frame_length_mm, frames, makeready_frames, separations, clicks, run_m, web_m, substrate_m2, printed_m2, speed_m_min, setup_s, running_s, total_s, click_cost, ink_cost, machine_cost, machine_price, cost, price, notes, hours}. The press's limits add the problems too_many_lanes, print_too_wide and web_too_wide; the lanes are still planned. A roll job whose press is a label press prints its layouts on it: the Layout JSON's print block is then {kind: "label", press, press_name, charge, frame_length_mm, breakdown: {makeready_s, running_s, wash_s}} plus the same estimate fields, from this plan when the job has label settings, else from the layout's used web in the press's longest frames.

Artworks#

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/

imposition_artworks_upload · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/from-files/

Add artwork picked in Files.

imposition_artworks_from_files · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/from-approval/

imposition_artworks_from_approval · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/

imposition_artworks_list · View in API reference

PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/

imposition_artworks_partial_update · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/bulk/

imposition_artworks_bulk · View in API reference

DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/

imposition_artworks_destroy · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/line-types/suggest/

imposition_artworks_line_types_suggest · View in API reference

DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/back-file/

imposition_artworks_back_file · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/pages/

imposition_artworks_pages · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/tile/

imposition_artworks_tile · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/tiling-report/

imposition_artworks_tiling_report · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/approval-versions/

imposition_approval_versions_list · View in API reference

Uploads are multipart: file (PDF, PNG, JPG, BMP, TIFF or WebP, up to 200 MB) and optionally name, quantity, rotation_preset, rotation_angles, shape_mode, custom_width and custom_height. PDFs start from their die path, images from their pixel contour; a PDF without a die starts from its trim box, with a warning. from-approval takes a version_id from the approval versions list (10 per page, searchable with q; by default only versions whose approval request was accepted). bulk sets quantity or rotation_preset on a list of ids, or deletes them. It also sets shape_mode (with custom_width and custom_height for custom_size, and die_from for pdf_closed_path): items it can't switch, such as an image asked for a die path or a file without the ink, are left as they were and listed in skipped with the reason.

back-file (multipart file, a PDF, and page, from 0) prints the item's back from that page of another PDF; it wins over back_page_number, and DELETE drops it. pages takes {"mode"} for a PDF of two pages or more: back (page 2 is the back), pairs (front, back, front, back…: one item per pair, copies of this one), each (every page an item, no backs) or front (the first page alone); it returns every item of the job. An imposed PDF of a job with two-sided items writes each sheet's back page after it, turned over by the job's back_flip.

from-files adds versions your team keeps in Files (the ids the Files API returns): {"items": [{"version_id": 812, "page_number": 0, "quantity": 500}]}, 1 to 50 items; page_number (from 0, default 0) and quantity (default 1) are optional. An item on page 0 of a file of two pages or more gets page 1 as its back_page_number; an item on another page gets none. The request is all or nothing: if any item is refused (a version of another team or of a file in the trash, a file that isn't a PDF or an image, a page the version doesn't have), nothing is added and the 400 lists the errors by item, in the order you sent them: {"items": [{}, {"version_id": ["File version not found."]}]}. To add more than 50, send several requests: each one is all or nothing on its own. It answers 201 with artworks and warnings. Each item gets a copy of the file's prep from the 1-up editor when the page was prepared there (a die, a print-ready file, an image's size; a file only opened there has none), with an upload's shape when that prep has no die (trim_box for a PDF, pixel_contour for an image). A prep that can't go to a job (a PDF worked on at another size) leaves the item as the file reads, with a warning {artwork_id, version_id, code, detail} (code scaled_pdf).

FieldIn the appRange or valuesMeaning
nameArtwork name–The artwork's name in lists, reports and run sheets.
quantityQuantity1 to 100000Pieces ordered.
rotation_presetRotation–job, none, 0_180, 0_90, quarter, any or custom.
rotation_anglesAngles (degrees, comma separated)–With custom: the allowed angles.
grain_directionGrainnone, horizontal, verticalThe artwork's grain: none, horizontal or vertical.
mirrorMirror–true to print and cut the artwork flipped left to right (window clings, back-lit film), before rotation.
product_typeProduct typeflat, bound, foldedflat, bound or folded. It doesn't change the nest.
shape_modeShapepdf_closed_path, pixel_contour, trim_box, custom_sizepdf_closed_path (Die path), trim_box, custom_size or pixel_contour.
custom_widthCustom width1 to 14400Custom size shapes: the width, centred on the page's trim box.
custom_heightCustom height1 to 14400Custom size shapes: the height.
page_numberFront page–The page nested and printed, from 0.
back_page_numberBack page–The back page, from 0; null for none. A file of two pages or more added on page 0 starts with page 1.
bleed_typeBleednone, margins, contournone (the job's bleed), margins or contour (this artwork's distance).
bleed_distanceBleed distance0 to 144This artwork's bleed.
selected_die_pathsDie paths–Indices of the artwork's paths that make the die; the largest is the outline.
path_indexOutline path–The path used as the outline when no die paths are selected.
spot_color_nameDie ink–The spot colour the die was drawn in, when it has one.
line_type_mappingsLine types–Path index to line type, e.g. {"0": "cut", "1": "crease"}.
splitSplitinherit, allow, neverinherit (the job's rule), allow or never: never keeps every copy of this item on one form or plate.
propertiesProperties–Product properties that ganging rules compare (stock, coating, customer, due and your own keys): an object of key and text.
own_sheetOwn sheet–On: this item never shares a sheet with other items.
materialMaterial–A material id of your library (null: none). It gangs as the item's stock, never sharing a sheet with other materials, and a sized material sets the job's sheet or roll and its cost.
inksInks–The declared inks per side, {"front": [...], "back": [...] or null}, used when Inks source is manual.
inks_sourceInks sourceauto, manualauto (the inks found in the file) or manual (the declared inks).
external_idOrder line–The order line id in your system, unique in the job (409 when taken).
metadataItem fields–The item's own fields for marks, a JSON object of at most 16 KB.
overrun_pctOver %0 to 500Offset: this item's most extra copies as a % of its quantity; null = the job's.
underrun_pctUnder %0 to 50Offset: this item's most copies short, as a %; null = the job's.
die_designSingle-up–A single-up dieline of the tooling library (id) the item sits on; null reads its own die lines.
die_registrationDie position–How a library single-up sits on the artwork when it has no die lines: {source, dx, dy, rot180} (pt), centred on the trim box plus the nudge. die_match (read-only) is the last die match.
die_fromDie from–Where the die path comes from: "" (the cut lines in the file) or a spot ink or "layer:<name>" listed in die_from_choices; writing it switches the item to its die path, and the ink becomes its only cut ink. Reads selection or rect for a die chosen in the 1-up editor.

Each artwork read also returns its size, has_polygon, oversize (too big for the printable area), warnings, page_count, spot_colors and a thumbnail_url.

tile splits a product larger than the printable area into overlapping tiles (Tiling a product larger than the media). The body is in points: direction (vertical, horizontal or grid), overlap, and optionally x_cuts / y_cuts (seams from the product's left and top edges; null or left out: as large as the media takes) and max_width / max_height (the largest tile; null or left out: the job's printable area less the bleed). An empty body or {"clear": true} removes the tiling. It returns {"artworks": [...]}, every item of the job; a tiling that can't be made is a 400 with the reason in detail. The product keeps its row with tiling (the stored tiling, {} when not tiled), tiles (how many) and tile_limit (width and height of the largest tile the media takes); each tile is an artwork of its own with tile_of (the product's id) and tile (index, row, col, count and its box in the product's page space). Tiles take every setting from their product: a PATCH, DELETE or any other change of a tile is a 400, bulk leaves tiles out, and deleting the product deletes them. tiling-report makes the tiling report of a tiled PDF product and returns its url.

Files versions and prep#

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/switch-version/

Use another version of the item's file.

imposition_artworks_switch_version · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/update-prep/

Copy the prep from Files again.

imposition_artworks_update_prep · View in API reference

An artwork made from a Files version (every upload, and every item added with from-files) also returns:

  • file_id and file_version_number: the file and the version the job uses;
  • file_latest_version_number and file_latest_version_id: the file's newest version the artwork can switch to (ready, a PDF or an image, with the artwork's page); the same as the artwork's when there is none, when the file is in the trash, and for an artwork imported from an approval (it prints that proof);
  • prep: {document_id, in_sync, document_updated_at, refusal} about the file's prep in the 1-up editor for this page (document_id is null when the page wasn't prepared there, only opened). in_sync is false when that prep changed since the artwork got its copy (or it never got one); refusal says why the prep can't go to a job ("" when it can).

All five are null for other artworks. switch-version takes {"version_id": 815}, a version of the artwork's own file that has the artwork's page (else 400): the artwork reads it, and its print-ready file is made again from it. It answers 409 approved_proof for an artwork imported from an approval. update-prep copies the prep again; it answers 409 {code, detail} when there is none (no_prep) or when it can't go to a job (scaled_pdf). Both answer 400 not_from_files for an artwork that isn't made from Files.

line_type_mappings returns every path's line type, including types that come from its ink. Send it back with your changes: a type that differs from the ink's becomes that path's own, and leaving out a path whose ink is mapped answers 400 (unmap the ink in the 1-up editor instead). selected_die_paths picks the die; path_index and spot_color_name follow the die and answer 400 when changed.

Dies and tooling#

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/match-dies/

imposition_jobs_match_dies · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/die/

Import a die file (CF2, DXF or PDF) as a die on hand on the job's sheet and plan the job on it.

imposition_jobs_die · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/cad-files/

"Attach CAD files": single-up CF2 / DXF files matched to items by file name (unlisted single-ups).

imposition_jobs_cad_files · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/accept-die-match/

imposition_artworks_accept_die_match · View in API reference

An offset job plans on dies by its die_policy (none, compare, standing, new; null = the team's default), with tool (a die to force under standing), die_cutter and die_settings. Items take overrun_pct, underrun_pct, die_design and die_registration (see the tables above). A job read adds a read-only tooling object: the effective policy, banner, the die coverage (fits, total, number), under standing the unfit items with a reason (near, mirrored, no_die_lines, artwork_multi_up, no_die_fits) and unfit_die (the forced die: the job's tool, else the die it was quoted on), matches per artwork, the press_costs a compare uses (derived from the press, or null: compare is refused), fill_default (the team's "fill empty stations" when die_settings.fill_blank is null) and the dies and die_cutters to choose from. An artwork read adds die_match: its best die (tool, kind, tier, dist_mm, usable), fits (every die on hand it fits), single_up (it has die lines) and accepted once confirmed.

  • POST …/match-dies/ matches every item again and answers {matches, tooling}.
  • POST …/die/ (multipart file, optional number, policy = standing or compare) imports a CF2, DXF or PDF die as a die on hand on the job's sheet and plans the job on it; 400 with issues when the file can't be read.
  • POST …/cad-files/ (multipart files) gives each single-up CF2 or DXF file to the item of the same name: {attached, unmatched, errors}.
  • POST …/artworks/{id}/accept-die-match/ with {"tool": 17, "kind": "A"} confirms a near match ("Use anyway").

Each solution of a run on dies carries tooling: scenario (its dies, such as tool:17 or new:A:8), rank, best, delta (more than the best, ranking money; null when unknown), groups (per die: candidate, kind, label, tool {id, number, ups, status}, ups, forms, good, printed, blank_stations per form, gap_pct), costs (paper, forms, press, die, die_price, companions, rerule, diecut, total; null without press costs; die, die_price and total null when it needs_rate, the press money null for a die on another sheet), over_pieces, why, break_even_pieces, folded (scenarios with the same plan shown under this one), notices, reason, failed (a group couldn't be planned: listed after every complete scenario) and customer_owned (it runs the customer's own exclusive die, listed first under compare). Its row's cost is the scenario total, with press_cost and die_cost beside it. Placements on a die carry station and, for copies added to fill a station, fill.

Pin-matrix stripping (see Pin-matrix stripping). die_settings also takes fit_pins (true/false; null follows the die-cutter's pin_fit_new_dies) and strip_overrides (new dies: {shape key: "stays_with_skeleton" | "falls_through" | "hand" | "stripping_tool"}, at most 400, each applying to every piece of that shape on the job). On a die-cutter with stripping settings, each candidate and die group carries stripping and strip_hand (the off-line hand stripping's [cost, price] per fed sheet), and costs adds strip_hand. A new die at another knife gap is a candidate of its own, keyed new:A:8:skeleton_bar or new:A:8:common_cut. stripping is:

  • the plan: method (pins, pins_unit, dedicated or none), machine (id, name), setup_min, hand_cost_per_k / hand_price_per_k (per 1,000 sheets), tool_cost / tool_price (the female board and lower pin unit, or the stripping tool), orders, sheets_for_choice and alternatives (method, compare_cost, unpriced);
  • the check: pieces, chips, by_grade (matrix, special, falls_through, stays_with_skeleton, machine, unsupported), pins, bars, openings, hand_pieces, with_breakers ([pieces, pins] with the suggested breaker knives cut), breakers, thin_min_mm, in_gripper, estimated, gap_mm, shift_mm ([dx, dy], the move onto the pin grid), notices, pins_machine_mm ([x, y, piece]: x in mm from the centre line, + to the operator's right looking in the feed direction, y from the lead edge) and detail (per piece: i, cls, grade, reason, flags and ref, {"hole": [station, k]} for a window or {"shape": key, "at_sheet_in": [dx, dy]}, plus id for a standing die's stored piece). The pieces' rings (shapes, sheet frame, inches) are fetched separately from the layout's stripping/.

A Plan freely job whose die_cutter strips with a pin matrix is checked after the run: its layouts carry stripping per form, the check only, with no money and no change to the plan. A layout's production.stripping is {"forms": [{"form", "die", "label", "key"}], "blocks": {key: stripping}}: each die's block once (without shapes), every form it runs on pointing to it by key. A standing die's grade marks are set on the tool (PATCH …/tools/{id}/waste-overrides/, see Equipment API).

Order data#

PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/metadata/

Merge into the job's order data (RFC 7396: null deletes a key).

imposition_jobs_metadata_merge · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/copy-data/

The item's per-copy rows (row k-1 prints on copy k), as JSON or CSV.

imposition_artworks_copy_data · View in API reference

PUT /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/copy-data/

Replace the per-copy rows (a JSON list of flat objects, or CSV with a header).

imposition_artworks_copy_data_replace · View in API reference

Order data is what your order system sends so that print marks can print it (see Order data in marks). It never makes a layout out of date.

  • Jobs take external_id (your order number, unique in your team), reference (a PO) and metadata (your own fields, a JSON object of at most 64 KB), with customer_name, due_at and priority. GET jobs/?external_id= finds a job by its order number. Creating or changing a job with an order number another job has answers 409 {"external_id": [...], "existing_id": 42}.
  • PATCH jobs/{id}/metadata/ merges into metadata (RFC 7396, Content-Type: application/merge-patch+json or JSON): keys you send are set, null deletes a key. It answers {metadata, warnings}.
  • Artworks take external_id (the order line, unique in the job; 409 the same way) and metadata (at most 16 KB); GET …/artworks/?external_id= finds one.
  • PUT …/artworks/{id}/copy-data/ replaces the per-copy rows: a JSON list of flat objects, or CSV with a header row (Content-Type: text/csv). Row 1 is copy 1. At most 10,000 rows (or the quantity, if larger) and 2 MB. It answers {rows, keys, warnings, missing}; GET returns the rows, ?format=csv as CSV.

warnings (on create, on the metadata merge and on copy data) list your team's required fields that are still missing, as [{field, message}]. Writes are never refused for them: order data often arrives in several calls.

curl -s -X PATCH "${JOBS}42/metadata/" -H "$AUTH" -H "Content-Type: application/merge-patch+json" \
  -d '{"po_number": "PO-000123", "rush": true, "old_note": null}'
curl -s -X PUT "${JOBS}42/artworks/7/copy-data/" -H "$AUTH" -H "Content-Type: text/csv" \
  --data-binary @serials.csv

Properties, ganging rules and inks#

GET /a/{team_slug}/imposition-layout/api/v1/ganging/rules/

The team's ganging rules and the ink shorthand parser.

imposition_ganging_rules_get · View in API reference

PUT /a/{team_slug}/imposition-layout/api/v1/ganging/rules/

Replace the team's rules (team admins).

imposition_ganging_rules_put · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/ganging/explain/

Why items can't share a form (every rule keeping each pair apart) and the job's gang groups, from the current inputs (no run needed).

imposition_ganging_explain · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/import-properties/

imposition_artworks_import_properties · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/inks/parse/

Parse declared inks: shorthand ("4/1 + PMS 185 C") or {"front": [...], "back": [...]}.

imposition_inks_parse · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/inks/refresh/

Read the artwork's inks again (the prepress result, or its declared inks) into its snapshot.

imposition_artworks_inks_refresh · View in API reference

An artwork's properties is an object of key: value pairs; a PATCH merges the keys you send and null deletes one. own_sheet gives the item forms of its own, split is its keep-together rule (inherit, allow or never), and inks takes declared inks as shorthand ("4/1 + PMS 185 C") or as {"front": [...], "back": [...]} lists of names; setting them makes inks_source manual, null clears them. Reads also return inks_resolved (the inks the run uses: status ok, pending or unknown, their source and each side's inks) and derived (sides, inks, finishes, product_type). Errors name the key: properties.coating.

A job's ganging adds rules to the team's (match_on, keep_apart, due_within_days, prefer_together); it can't drop the team's keys. Reads return ganging_resolved, the rules a run uses. Rule errors name the path, such as ganging.match_on[1]. The team's rules (ganging/rules/) also hold the custom property registry (properties); team admins write them. bulk also sets split, own_sheet, material (a material id, null to clear), inks or properties (keys to set, null to clear) on a list of ids.

jobs/{id}/ganging/explain/?artworks=12,15 lists, for each pair, whether the items can share a form (true, false or "conditional" when only the ink limit keeps them apart) and every rule that doesn't allow it, with both values. import-properties/ takes a CSV file or JSON rows and dry_run (default true); see Item properties for the columns.

Runs#

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/

Start a run in the background (409 while one is running).

imposition_jobs_run_start · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/

RunState: status and progress, and the Solutions rows changed since the cursor (every live row with reset when there is no cursor or the run differs).

imposition_jobs_run_state · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/stop/

imposition_jobs_run_stop · View in API reference

POST …/run/ takes optional method, run_type, method_settings and time_limit_s (they are saved on the job) and answers 202 with the run state and its warnings. It answers 400 with field errors when the run can't start, for example {"method": ["N-up needs sheets."]}, and 409 while another run is in progress.

Poll GET …/run/?cursor=…&run=… every second or two. The run state has status (idle, queued, running, stopping, completed, stopped or failed), message, error, elapsed_s and the run's solutions: the layouts it found, as rows that change while it searches.

  • The first poll (no cursor) answers reset: true and every live solution. Keep cursor and result_run_id from each answer and send them back as cursor and run: the next answer lists only the rows added or changed since (at most 100; has_more: true means poll again at once). A row that was dropped comes once with status: "removed" and its removed_reason. When run is no longer the run whose rows are stored (a new run wrote its first layouts), the answer is a reset again: drop what you hold.
  • Each solution has its ref (c- and 12 hex digits), status (streamed, then verified once the run's final checks pass), seq (arrival order), found_ms, method, run_type, sheet_count or used_length_in (rolls), form_count, utilization, unplaced_count, strokes, slits, cost and printed_sheets (offset), plates_physical and plates_assumed_as (offset: the physical plates, one per ink and side of every form, and "4/0", "4/4" or "mixed" when items without known inks were counted as CMYK, else null; plates_physical is null on a digital press), passes_total (offset plans made with the press's ink model, else null), plate_count (deprecated: the form count, the same as form_count), split_count, split_ids, advisory, sig and repeats (identical-looking results share a sig; repeats counts them), stale (the job changed since the run), layout_id (its saved copy) and rank_key. Sort by rank_key (compare the lists number by number), then seq: that is the order the server ranks in.
  • The answer also has candidate_count, distinct_count, best_uid, lower_bound (with lower_bound_kind), selected (the job's chosen result, see below) and last_export.

POST …/run/stop/ stops the run and keeps the layouts found so far.

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/thumbs/

Compact sheet-1 drawings of solutions and saved layouts: {ref: thumb} (unknown refs left out).

imposition_jobs_run_thumbs · View in API reference

GET …/run/thumbs/?refs=c-…,l-… returns small drawings of sheet 1 of up to 20 layouts, {ref: thumb}: w and h (0–1000 on the long side), copies, and pieces as [x, y, w, h, colour, angle] boxes with outlines for sheets of up to 300 pieces; a sheet with too many pieces comes back as a coloured grid instead of boxes. colour is the artwork's position in the job, or its gang group with color_by=group.

Selection#

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/selection/

Use a layout: {"ref", "run_id", "acknowledge": [codes]}.

imposition_jobs_selection_set · View in API reference

DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/selection/

imposition_jobs_selection_clear · View in API reference

POST …/selection/ with {"ref": "c-…", "run_id": "<result_run_id>"} chooses the job's result: Production, the Report and the job list then show it. A solution of the run is saved as a copy first (an existing copy is used as it is, edits included); a saved copy (l-…) needs no run_id. The answer is {"selected": …, "layout": …}.

  • 409 with codes asks you to confirm and post again with "acknowledge": [the codes]: exported when the job's latest export is of something else (files already sent won't match), breaks_keep_together when the solution splits items set to keep together (names lists them).
  • 409 {"code": "run_changed"}: a newer run replaced the solutions you were looking at. 410 {"code": "removed", "reason": …}: the solution was dropped. 422 {"code": "failed_checks", "problems": […]}: a solution not verified yet failed the checks; nothing was saved.

DELETE …/selection/ clears the choice (?acknowledge=exported when it is the latest export).

Layouts#

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/

imposition_layouts_list · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/

imposition_layouts_retrieve · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/

imposition_layouts_create · View in API reference

PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/

imposition_layouts_partial_update · View in API reference

POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/reset/

imposition_layouts_reset · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/report/

Comparison rows: sheets / length, utilisation, cut and print time, material and prices.

imposition_jobs_report · View in API reference

A layout is addressed by its ref: c- and 12 hex digits for a layout of the last run, l- and a number for a saved copy (the workspace's solutions and saved solutions). GET …/layouts/{ref}/ returns the layout with its placements, production data and times; it sends an ETag, so a repeat request with If-None-Match gets 304 while nothing changed. POST …/layouts/ with {"candidate": "<uid>"} saves an editable copy of a run layout, named "Solution #3 · 11:07" (its rank and the time; older copies with the previous default name, "Layout #3 · 11:07", were renamed the same way). PATCH on a saved copy sets its name, marks it selected, or moves pieces (pieces with the revision you edited; 409 if it changed meanwhile). The list returns the saved copies. GET …/report/?refs=c-…,l-… returns the Report rows for up to 50 refs.

On an offset layout, production.gang has forms (the form count), plates_physical and plates_assumed_as; production.gang.plates is deprecated and holds the form count, as before. Each form in production.forms carries inks with plates, plates_front, plates_back and source: "plan" when the press's ink model planned it (with passes and mode), "count" when it was counted (unknown inks: the press's passes and mode for the counted plates; no press: passes is null and mode is "count"). The layout's plates block (offset) says where the plate money comes from: source (platemaker, press, job_form or unpriced), label, forms, plates, plates_front, plates_back, the platemaker's time (setup_s, run_s, total_s, wait_s), cost, price, priced and notes (codes such as plates.unpriced). A Report row has form_count (plate_count is its deprecated alias), plates_physical, plates_assumed_as, passes, and the plates money plates_cost, plates_price, plates_source, plates_label, plates_notes and plates_s (platemaker time, part of total_s); plates_price is null when the plates aren't priced, never 0. total_price adds material, cutting, printing and plates (plates that aren't priced add nothing).

The layout's breakdown is the Report's: forms (each distinct sheet's copies, pieces, items and utilization), items (each artwork's ordered, produced, over and the forms it is on) and good_sheets. A roll longer than one cutter bed adds breakdown.roll: length_in, bed_length_in and beds, each with index, start_in, end_in, length_in, pieces, utilization and items (id, on_bed); each item then also lists the beds it is on (1-based). A piece belongs to the bed its cut starts in, as in the one-page-per-bed cut file.

Exports#

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/imposed-pdf/

imposition_layouts_imposed_pdf · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/cutfile/

imposition_layouts_cutfile · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/cut-program/

The N-up knife program: one row per step (back gauge in the job's display unit); `jdf`: a JDF Cutting node with a cut block per piece, for guillotine software that plans the knife itself.

imposition_layouts_cut_program · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/run-sheet/

The offset run sheet: forms, artworks × slots, run, makeready, printed, produced, overrun and the form's plates (front and back).

imposition_layouts_run_sheet · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/plate-list/

The offset plate list: one row per physical plate (one ink on one side of a form) with its side, pass and a suggested press unit (blank without a press or the ink model).

imposition_layouts_plate_list · View in API reference

  • imposed-pdf/ takes sheet (from 0) for one form only; the file name ends in form-1, form-2… on offset (plate-1 before forms and plates were told apart) and sheet-1 otherwise. On a roll kept within beds, pages=frames gives a page per bed, repeated ones too, each with its own marks; the file name ends in imposed-frames.
  • A layout (GET one, or the POST that saves a solution) takes compact=1: pieces of the same shape then share it. Each distinct outline, cut, method, lines and holes, relative to the piece's x and y, is listed once in layout.templates, and a piece names its template in tpl (a cut equal to the outline is "outline"). Add the piece's x and y to a template's points to get the piece's own. Without it, every piece carries its geometry.
  • cutfile/ takes format = pdf, dxf, cff2 or zcc (default: the cutter's cut file format), sheet (from 0) for one sheet only and, for roll jobs kept within beds, pages=beds (PDF only).
  • cut-program/ takes format = csv (back gauge in the job's display unit), json (points) or jdf (a JDF 1.4 Cutting job with a cut block per piece, in points: see Exports); it answers 404 for layouts that aren't N-up.
  • run-sheet/ and plate-list/ answer 404 for layouts that aren't offset plans. The run sheet's first column is form (it was plate), followed later by plates, plates_front and plates_back.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/die-cf2/

The standing die's CF2 (its own file: one SUB per kind, a call per station) of a layout on a die.

imposition_layouts_die_cf2 · View in API reference

  • die-cf2/ answers the standing die's own CF2 for a layout on a die (404 otherwise).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-map/

The pin map: one page per die, at 1:1 when the sheet fits A3 or tabloid.

imposition_layouts_pin_map · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-list/

One row per stripping pin, in the die-cutter's frame (mm).

imposition_layouts_pin_list · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-dxf/

One die's knives, waste pieces and stripping pins on layers KNIFE, WASTE and STRIPPING_PINS (mm).

imposition_layouts_pin_dxf · View in API reference

GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/stripping/

The pin-matrix check's waste shapes (sheet frame, inches), fetched when the viewer's Stripping pins layer is switched on: {forms: [{form, key}], shapes: {key: {shape: ring}}}, each die's once.

imposition_layouts_stripping · View in API reference

  • pin-map/ (PDF, one page per die, at 1:1 when the sheet fits A3 or tabloid), pin-list/ (CSV: die, form, piece, class, grade, reason, pin, x_mm, y_mm, side, grid_col, grid_row, bar) and pin-dxf/ (one die, die from 0 in pin-map page order; DXF in mm with layers KNIFE, WASTE and STRIPPING_PINS) answer 404 for a layout without a pin-matrix check. On such a layout the imposed PDF also carries a non-printing Stripping layer.
  • stripping/ answers the waste shapes the viewer draws, each die's once: {"forms": [{"form", "key"}], "shapes": {key: {shape: ring}}}.

Every export answers 409 once the job's inputs changed since the layout was made: run again. Each file you download is recorded on the job (the last 20: layout, revision, kind and time), which is what the exported confirmation above compares with. A layout edited into overlaps still exports, with an X-Layout-Warning header; a cut PDF longer than 200 in carries an X-Cut-File-Warning header. What the files contain is on Exports.

With print marks on the job, the imposed PDF gets a Marks layer and the cut file the registration marks, and a cut file of one sheet is named from its sheet code (see Cutter registration and job codes). The marks are checked first: a problem that blocks the export answers 422 {"detail": …, "code": "marks_gate", "issues": [...]} (grouped as in the marks API's check/) and no file is written. A successful download carries X-Marks-Count (marks in the file) and, when there are warnings, X-Marks-Warning.

Every operation#

API operations tagged imposition
MethodPathWhat it does
GET /a/{team_slug}/imposition-layout/api/v1/approval-versions/ imposition_approval_versions_list
GET /a/{team_slug}/imposition-layout/api/v1/ganging/rules/ The team's ganging rules and the ink shorthand parser.
PUT /a/{team_slug}/imposition-layout/api/v1/ganging/rules/ Replace the team's rules (team admins).
POST /a/{team_slug}/imposition-layout/api/v1/inks/parse/ Parse declared inks: shorthand ("4/1 + PMS 185 C") or {"front": [...], "back": [...]}.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/ Find jobs by order number: [{id, name, external_id, customer_name, reference, due_at, priority, status, updated_at, url}], newest first.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/ imposition_jobs_create
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/ imposition_artworks_list
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/ imposition_artworks_upload
PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/ imposition_artworks_partial_update
DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/ imposition_artworks_destroy
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/accept-die-match/ imposition_artworks_accept_die_match
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/back-file/ imposition_artworks_back_file_2
DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/back-file/ imposition_artworks_back_file
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/copy-data/ The item's per-copy rows (row k-1 prints on copy k), as JSON or CSV.
PUT /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/copy-data/ Replace the per-copy rows (a JSON list of flat objects, or CSV with a header).
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/inks/refresh/ Read the artwork's inks again (the prepress result, or its declared inks) into its snapshot.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/line-types/suggest/ imposition_artworks_line_types_suggest
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/pages/ imposition_artworks_pages
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/switch-version/ Use another version of the item's file.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/tile/ imposition_artworks_tile
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/tiling-report/ imposition_artworks_tiling_report
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/{id}/update-prep/ Copy the prep from Files again.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/bulk/ imposition_artworks_bulk
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/from-approval/ imposition_artworks_from_approval
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/from-files/ Add artwork picked in Files.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/artworks/import-properties/ imposition_artworks_import_properties
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/ganging/explain/ Why items can't share a form (every rule keeping each pair apart) and the job's gang groups, from the current inputs (no run needed).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/ imposition_layouts_list
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/ imposition_layouts_create
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/ imposition_layouts_retrieve
PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/ imposition_layouts_partial_update
DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/ imposition_layouts_destroy
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/cut-program/ The N-up knife program: one row per step (back gauge in the job's display unit); `jdf`: a JDF Cutting node with a cut block per piece, for guillotine software that plans the knife itself.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/cutfile/ imposition_layouts_cutfile
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/die-cf2/ The standing die's CF2 (its own file: one SUB per kind, a call per station) of a layout on a die.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/imposed-pdf/ imposition_layouts_imposed_pdf
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-dxf/ One die's knives, waste pieces and stripping pins on layers KNIFE, WASTE and STRIPPING_PINS (mm).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-list/ One row per stripping pin, in the die-cutter's frame (mm).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/pin-map/ The pin map: one page per die, at 1:1 when the sheet fits A3 or tabloid.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/plate-list/ The offset plate list: one row per physical plate (one ink on one side of a form) with its side, pass and a suggested press unit (blank without a press or the ink model).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/report-pdf/ The solution's report: a summary page, then each distinct sheet with its drawing, the times it is printed and what is on it.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/reset/ imposition_layouts_reset
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/run-sheet/ The offset run sheet: forms, artworks × slots, run, makeready, printed, produced, overrun and the form's plates (front and back).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{job_pk}/layouts/{ref}/stripping/ The pin-matrix check's waste shapes (sheet frame, inches), fetched when the viewer's Stripping pins layer is switched on: {forms: [{form, key}], shapes: {key: {shape: ring}}}, each die's once.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/ imposition_jobs_retrieve
PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/ imposition_jobs_partial_update
DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/ imposition_jobs_destroy
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/cad-files/ "Attach CAD files": single-up CF2 / DXF files matched to items by file name (unlisted single-ups).
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/die/ Import a die file (CF2, DXF or PDF) as a die on hand on the job's sheet and plan the job on it.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/ LabelLanesJSON: the job's label settings (defaults filled in), the artwork's turn on the web (angle), the items that don't fit the label at that turn (warnings) and the lane plan (rows, frames, length, lanes, frame runs, rolls, items, problems) and the label press's estimate of the run (frames, clicks, web, time, cost and price; null without a label press).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/frames-pdf/ The frames PDF: one page per frame run (the run list gives each page's copies), or every frame.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/rolls/ The roll list: each lane's finished rolls with labels, length and diameter in the job's unit.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/labels/run-list/ The run list: per page of the frames PDF, its frames, copies and what each lane holds.
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/match-dies/ imposition_jobs_match_dies
PATCH /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/metadata/ Merge into the job's order data (RFC 7396: null deletes a key).
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/report/ Comparison rows: sheets / length, utilisation, cut and print time, material and prices.
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/ RunState: status and progress, and the Solutions rows changed since the cursor (every live row with reset when there is no cursor or the run differs).
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/ Start a run in the background (409 while one is running).
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/stop/ imposition_jobs_run_stop
GET /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/run/thumbs/ Compact sheet-1 drawings of solutions and saved layouts: {ref: thumb} (unknown refs left out).
POST /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/selection/ Use a layout: {"ref", "run_id", "acknowledge": [codes]}.
DELETE /a/{team_slug}/imposition-layout/api/v1/jobs/{id}/selection/ imposition_jobs_selection_clear

All “imposition” operations in the API reference

Last updated Nov. 17, 2026