Imposition API

The imposition API does everything the workspace does: jobs, artwork, runs, layouts and exports. 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#

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

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.

Artworks#

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 (25 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.

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).

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.

Files versions and prep#

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.

Order data#

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#

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, 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 …/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, plate_count, utilization, unplaced_count, strokes, slits, cost and printed_sheets (offset), 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 …/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 …/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#

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. 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. 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.

Exports#

• imposed-pdf/ takes sheet (from 0) for one form or plate only.
• cutfile/ takes format = pdf, dxf or cff2 (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) or json (points); it answers 404 for layouts that aren't N-up.
• run-sheet/ answers 404 for layouts that aren't offset plans.

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#