Prepress API

The prepress API does what the 1-up editor does, for one artwork of an imposition job: its line types and die, bleed and the print-ready file, the 3D scene, trapping and proofs. Every endpoint is under

/a/{team_slug}/prepress/api/v1/artworks/{id}/

where {id} is the artwork's id in the imposition API. An artwork of another team is a 404. The same endpoints work on a page of a PDF or image in Files, under /a/{team_slug}/prepress/api/v1/documents/{id}/ (see Files documents). Lengths and coordinates are PDF points (1/72 in) in the page's own coordinates, with y pointing up.

Every call takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session that also sends its CSRF token when it changes data (see authentication).

A quick tour#

ART=https://app.example.com/a/acme/prepress/api/v1/artworks/42/
AUTH="Authorization: Api-Key $API_KEY"

# The editor state: inks, paths, line types, die, frames
curl -s "$ART" -H "$AUTH"

# Map the spot colour "CutContour" to Cut and "Crease" to Crease
curl -s -X PATCH "$ART" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"ink_mappings": {"CutContour": "cut", "Crease": "crease"}}'

# Make the print-ready file with 3 mm (8.5 pt) of bleed; 202 means it runs in the background
curl -s -X POST "${ART}bleed/generate/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"distance_pt": 8.5, "method": "auto"}'
curl -s "${ART}bleed/status/" -H "$AUTH"

# Trap it for offset, then poll the trap state
curl -s -X POST "${ART}trap/run/" -H "$AUTH" -H "Content-Type: application/json" -d '{"preset": "offset"}'
curl -s "${ART}trap/" -H "$AUTH"

The editor state#

The state has artwork (name, quantity, pages, shape, whether a print-ready file is in use), spec (the settings below), extracted, inks, paths (each with its id, ink, layer, closed, bbox and its points as xy, a flat [x0, y0, x1, y1, …] list), line_types (path id to line type), line_type_counts, die (outer, holes, bbox, area, is_rectangle, source, path_ids, inks and warnings) or die_error, bleed_plan, print_ready_stale, file_bleed_pt, frames (the page boxes of the original and the print-ready file) and trap (the trap status).

extract/ reads the page's inks and paths again, keeping the line types that still match (see Inks and line types). Nothing can be mapped until the artwork has been read once.

Change the settings#

Send only what changes. Objects merge into what is stored, so two clients changing different keys never undo each other. The answer is the state, without paths.

Line types are the keys of the line types table: cut, crease, perforation, score, kiss_cut, v_cut, thru_cut, partial_cut, bleed, varnish, foil, glue, annotation, technical and ignore. The editor's names for bleed corners are Sharp (miter), Round and Flat (bevel). Changing ink_mappings, path_mappings or die, or sending adopt_die_shape, is refused with 409 extract_first while the artwork's paths are not the ones last read: call extract/ first.

The 3D scene#

• material.preset: sbs_coated, sbs_uncoated, kraft, corrugated_e, corrugated_b, corrugated_c, corrugated_bc, metallized, clear_pet, frosted_pet, holographic, label_white or label_clear (see Board and material). The preset is the look; caliper_mm is the thickness.
• material.board_id: the board catalogue key the material stands for, such as board.sbs_c1s_18pt (lowercase letters, digits, _ and ., at most 64 characters; anything else is dropped). It doesn't change the look. material.flute_axis: x or y (the default), the direction corrugated flutes run in the sheet.
• finishes[].type: gloss_varnish, matte_varnish, soft_touch, spot_uv, foil_gold, foil_silver, foil_holo, foil_color, emboss, deboss or white_ink (see Finishes). params takes strength and gloss (0 to 1), roughness (0.02 to 1), raise_um and deboss_um (0 to 200), height_mm (0 to 2), bevel_mm (0.05 to 3) and color (#rrggbb), each only for the types that use it. A plate can have one finish.
• lighting.preset: studio, softbox, daylight or retail (see Lighting, snapshots and 3D files).
• fold.sequence: depth (the default) folds the panels next to the base first and the outermost flaps last; together folds every hinge at once; order follows the dieline's fold steps (hinges[].fold.sequence of the structure), and is depth without them.
• fold.angles: an angle you send wins over the dieline's (hinges[].fold.angle), which wins over the default of the hinge's kind.

Unknown keys are dropped and numbers are clamped to their ranges. A scene over 64 KB is refused.

The print-ready file#

bleed/generate/ takes the same bleed settings as PATCH (saved first) and in_request. It answers 200 with the state when the file was made, or 202 with a job (id, status: queued, running, done or failed, error) when the band is large: poll bleed/status/ until the job is done. in_request: true makes a large band while you wait, when it is small enough. tools/apply/ makes the print-ready file again with the output tools, keeping the bleed the file in use has. bleed/revert/ goes back to the original. What each setting does is on Bleed and the print-ready file.

bleed/preview/?distance_pt=&corner= returns the band's rings and area without making anything. file/ returns the PDF: ?which=source for the original, effective (the default) for the file in use, and download=1 to download it.

Geometry and carton structure#

geometry/ is the artwork's layout on its page (version 1, in points): frame (MediaBox, CropBox, rotation), trim_box (the die's box, or the page's TrimBox without a die), bleed_box, bleed_pt, safe_box (or null), die (outer, holes, path_ids), lines by line type, page_index and meta (artwork, job, name, quantity, approval version, file hash).

structure/ is the 3D carton: its panels, hinges (each with its id, the panels it joins and its kind), the root panel, the fold tree and warnings (see The 3D carton). A hinge's id depends only on its two ends, rounded to 0.1 pt, then sorted. When the source PDF carries a dieline's fold data (the dieline.json attachment, see The 3D carton), a crease's entry applies to the hinges whose id is its key; else to those it names another way (a drawn crease lying along the hinge, or a coordinate on a 0.05 pt rounding tie rounded the other way); else, when it gives its span (a, b, with die_bbox for a die placed elsewhere), to every hinge lying along that span. Then:

• each hinge it matches has fold: angle (signed degrees, positive folds the print outside), sequence (the fold step, 1 first) and kd_angle (the flat-glued angle, or null). Other hinges have fold: null.
• root_source is hint when the root is the panel the data names (given for the scene's base panel, largest otherwise).
• seeded_material is the scene's new material on the one request that set the dieline's board.

plates/ lists the page's plates (name, kind, cmyk, rgb), process first; ?file=source reads the original.

Inks#

inks/ is what the job knows about the artwork's inks, per side, for ink-aware ganging: status (ok, pending until the editor has read the artwork, or unknown for images and unreadable files), basis (vector, raster or mixed), and front and back, each a list of inks with key, variant, name, kind, role, coverage_pct, cmyk, rgb, opaque, clear and process_step. Technical inks are left out. It never reads the file for you.

ink/?x=&y=&size=&file= is the densitometer of the editor: the tint of every plate over a size pt square (0.25 to 18, default 1) at a point, and the total ink (see The Tools tab).

Renders and 3D assets#

render.png/ draws the page with overprint simulated: hide (plate names separated by |, layers as layer:<name>), dpi (9 to 1200, default 96), clip (x0,y0,x1,y1 in points) and file (effective or source). The resolution may be lowered to keep the image a reasonable size; the X-Render-Dpi header says what was used. assets/ is the manifest of the 3D textures, with a URL for each file. Page and trap renders, ink samples, 3D assets and shares are limited to 120 requests a minute per user; over it you get 429.

Trapping#

trap/ returns the trap state (none, queued, running, trapped, stale or failed), stale_reason (settings or file), in_file, enabled, layer_on, the settings, the presets, the editable params with their defaults, the ink table (inks), the kinds, the audit_options, and the last result (generated) and check (audit, with a thumbnail URL for each checked area). Poll it while a job runs.

trap/run/ saves any settings it is given and starts a run (202): preset (offset, flexo, digital or custom), base (offset or flexo, what Custom starts from), overrides (below; only used by custom), inks ({ink name: {"kind": "opaque", "nd": 1.2}}, kinds normal, transparent, opaque, opaque_ignore or technical, nd from 0.001 to 4) and audit_um (0, 25, 50, 75, 100 or 150; 0 skips the check). Digital makes no traps: its run is refused with no_trapping.

trap/state/ {"on": true} makes the traps print by default (conventional press), false switches them off (digital). trap/strip/ removes the trap layer. Both answer {trap, state}. trap/render.png/ draws the file in use with the traps forced on (on=1) or off (on=0), and trap/overlay.png/ the trap areas alone.

The overrides keys:

What each setting does, and its offset and flexo default, is on Trapping settings and inks.

Share a proof#

A multipart POST with include (flat and/or 3d), name, share_mode (simple or advanced) and an optional poster image for reviewers who can't show 3D. The answer (201) has url (the approval link), version_id, version_number, request_id and views, the views the link offers: 3d is left out when the 3D files could not be saved. See Sharing proofs from the editor.

Files documents#

A document is one page of a version of a file in Files, opened in the editor (see Files and images). POST /a/{team_slug}/prepress/api/v1/documents/ with a version_id from the Files API and a page_number (0 for the first page) answers with the document's id, whether it was created, its editor_url and its state: the first time, it is made and seeded from the nearest earlier version's document, as opening the editor does. A print-ready version saved from the editor opens the version it was made from (so bleed is never added on top of bleed). Other kinds of file answer 400 not_supported, a page the file doesn't have no_page, and a version of another team or of a file in the trash 404. Every endpoint above works under /a/{team_slug}/prepress/api/v1/documents/{id}/, with prepress_document_ operation ids (prepress_document_state, prepress_document_update, prepress_document_bleed_generate…). A document's state has artwork.kind: "document", job_id and quantity null, and artwork.document: file_id, version_id, version_number, latest_version_number, raster (an image, read through its print PDF), raster_params, source_error, carried_from (document_id, version_number) and review with review_message: "" (prepared), preparing, needs_review (the die was lost or its cut lines changed), not_prepared (also a preparing that no worker finished within 40 minutes) or storage_full. Documents of a file in the trash answer 404. Its geometry/ meta has document_id, file_id, file_version_id and version_number, with artwork_id, job_id and quantity null.

• PATCH document/ sets back_page_number (another page of the file, or null) and product_type (flat, bound or folded); die_checked: true clears needs_review once a person has checked the die.
• POST save-version/ with an optional note (up to 500 characters) makes the up-to-date print-ready file the file's next version (source prepress, the same bytes). It answers 201 with status (added, unchanged or pending), version (id, number) and file_url, or 409 with no_print_ready, stale, busy or superseded (a newer version was added after this one; saving would make the older file current on top of it). An image's print-ready file is a PDF, so the file's kind becomes pdf and its download name ends in .pdf.
• GET download/ downloads the print-ready file as <file> (print-ready).pdf (404 without one).
• GET /documents/?file_id= lists the documents of a file in Files (each page of each ready version that was opened in the editor), newest version first, as {file_id, documents}. Each has id, version_id, version_number, page_number, page_count, state, review with review_message, carried_from, print_ready, can_save with save_refusal, saved_as (the version number it was saved as, or null), updated_at and urls (editor, save_version, download). state is ready, stale (made before the latest changes), building, needs_review, not_prepared, storage_full or none (no print-ready file). print_ready is null or trim_pt ([width, height]), bleed_pt, traps, size (bytes) and built_at. A file of another team is a 404.
• GET links/ is what the editor's File tab shows: the file's file_id, name, path, file_url, properties_url, folder_url, properties (key, label and the value as text, set values only), tags, versions (id, number, source, derived_from, current), this document's status (as in the list) and jobs: available (whether imposition artworks can be made from Files versions yet), items, the artworks made from this version and page (artwork_id, name, job_id, job_name, job_url, laid_out, selected, in_sync), and refusal: why this document's settings can't go to a job (a PDF worked on at another size with Scale), "" when they can.
• POST apply-to-jobs/ with artwork_ids copies this document's settings and up-to-date print-ready file onto those artworks (only artworks of your team made from this version and page change) and answers updated (their ids) and available. Until artworks can be made from Files versions, updated is always empty. An image's size goes with the copy (the artwork prints the image's print PDF at that size); a scaled PDF answers 409 scaled_pdf.
• share/ proofs the print-ready file while it is up to date, else the version itself; the round is added to the approval artwork of the file. A full storage answers 507 (quota_exceeded) when an image's print PDF has to be stored first.

Die creation and size (Files documents)#

These endpoints exist for Files documents only (see Create a die and Size and resolution), under /a/{team_slug}/prepress/api/v1/documents/{id}/.

• GET die/create/ answers params (the created die's parameters, or null), meta (its last run: path_ids, die_path_ids, trim, stats, warnings, at, or error), inks (the die inks to offer, your team's last one first) and defaults (shape, contour, drawn).
• POST die/preview/ with {"params": {…}} answers the die they make, without saving: outer and holes (rings of [x, y]), bbox, lines (the creases and extra cuts: points, closed, type), stats, warnings and the normalised params.
• POST die/create/ with {"params": {…}} makes it the document's die and answers the editor state. Its lines join paths with source created and the ink Crease or the die ink, mapped to cut and crease in path_mappings; the die selects the outline and holes, and the created ink joins inks with source created. The parameters are stored as spec.die.created, the last run as spec.die.created_meta; both stay when the die mode changes, and are carried to new versions. POST die/remove/ takes it all away.
• POST die/points/ with action (smooth, straighten or snap), points ([u, v] fractions of the trim box, 2 to 4000) and closed answers the new points. iterations (1 to 5), tolerance_pt and snap_pt tune them.
• GET size/ answers kind (raster or pdf), scale, resample_ppi, unsharp, size_pt and natural_pt (the size at scale 1), and for an image pixels, source_pixels, native_ppi, dpi_source (metadata or assumed) and effective_ppi; limits (warn_ppi, error_ppi, profile) are the preflight profile's image resolution limits, max_pixels and page_limits_pt the limits a new size must respect.
• POST size/ with scale, and for an image resample_ppi and unsharp, applies a new size, reads the page again and answers {size, state}.

The parameters (version 1) are kind (shape, contour or drawn), ink (a spot name, Dieline by default), trim (the trim size they were made for; filled in when left out), the block of the kind, and lines ([{"type": "crease" | "cut", "points": [[u, v], …], "closed": false}], at most 200). Positions are fractions of the trim box from its bottom-left corner, so the die follows the page when its size changes; lengths are points.

{
  "version": 1,
  "kind": "contour",
  "ink": "CutContour",
  "contour": {"source": "alpha", "offset_pt": 4.5, "keep_holes": false, "single_piece": "bridge"},
  "lines": [{"type": "crease", "points": [[0.1, 0.5], [0.9, 0.5]]}]
}

• shape: shape (rectangle, rounded or ellipse), size (trim or custom, with width and height as shares of the trim and center [u, v]), radius_pt (0 to 14400) and offset_pt (-144 to 144).
• contour: the fields in Create a die.
• drawn: points (3 to 4000 [u, v]), closed (it must be true), smooth (0 to 5) and snap_pt (0 to 72).

Errors#

Errors are {"detail": "…", "code": "…"}, with the message in the user's language and a stable code:

See the API overview for the errors every API shares.