Equipment API

The equipment API manages the same printers and cutting machines as Equipment in the app. Estimates and imposition layouts take their print and cut times, costs and cut-file formats from them. All calls are team-scoped under /a/<team_slug>/production/api/v1/ and need an API key (see the API overview).

Machines and printers work the same way, so this page describes them together. Sizes are in millimetres, speeds in mm/s and m²/h; test cuts and test prints take their part sizes in inches (see Units and measurements). The API reference lists every field; Printers and Cutting machines explain what they do.

List, read and change#

Lists return the active machines or printers as a plain array; add ?include_inactive=1 to include archived ones.

• Deleting archives. DELETE archives the machine or printer instead of removing it, so estimates and layouts that refer to it keep working. Restore it with PATCH {"is_active": true}. Archiving the default hands the default to the next active one, by name.
• Checks. A machine's default_cut_speed_mm_s can't exceed its max_speed_mm_s. A printer needs at least one entry in modes ([{"name", "speed_m2_h", "passes"}]); default_mode must name one of them (blank means the first). A roll printer never keeps a max_print_length_mm.

The printer endpoints have the same shape: production_printers_create, production_printers_retrieve, production_printers_partial_update and production_printers_archive.

Start from a preset#

Presets hold manufacturers' published specifications plus estimated starting values for everything a spec sheet doesn't give.

Both return {"manufacturers": [{"name", "machines": [...]}]}. Each entry has its specifications, the defaults a new machine or printer gets, and estimated_fields, the values that are estimates rather than published figures. Machine presets also carry tool_speed_guidance.

curl -sS -X POST -H "Authorization: Api-Key $API_KEY" -H "Content-Type: application/json" \
  "https://app.example.com/a/acme/production/api/v1/machines/from-preset/" \
  -d '{"preset_key": "<a key from presets/>", "name": "Cutter 1"}'

name is optional. An unknown preset_key answers 400. Printers created from a preset start with prices at 0, so set your rates before they add to quotes.

The team default#

New material groups in estimates use the team's default machine and printer.

An archived machine or printer can't be the default (400): restore it first.

Test cuts and calibration#

A test cut lays identical parts out in a grid on the machine's bed and returns the full time breakdown and the price:

{"shape": "rect", "width_in": 4, "height_in": 6, "quantity": 50, "spacing_in": 0.25, "profile": "material:7"}

Time a real job on the machine and send the same body plus measured_seconds (1 second to 7 days). The answer suggests an efficiency factor: the measured time minus the fixed overheads, divided by the estimated motion time, kept between 0.2 and 5. If you agree, save it with PATCH {"efficiency_factor": …} on the machine.

Test prints#

Send either area_m2, or width_in × height_in × quantity (1 to 500), plus sheets (1 to 10,000) and a print mode (blank for the printer's default mode). The answer gives the time (setup, printing, sheet handling), the cost and the price including ink.

Presses and guillotines#

Presses (sheetfed offset and digital) and guillotines have the same list, create, read, update, archive and set-default endpoints under presses/ and guillotines/. A press's default is per technology group: one for offset, one for digital.

• Typed settings. coaters is a list of {"side": "front"|"back"|"both", "types": ["aqueous", "uv"], "flood_only"} (at most 4); special_stations a list of {"index", "loaded", "allowed", "layers"} (at most 3, loaded one of allowed when that is set); nonprintable is {"lead", "trail", "left", "right"} in mm; fixed_inks and house_inks are ink keys such as process:cyan or pantone:185-c.
• Checks. A perfecting press needs perfect_after_unit from 1 to units − 1, and only offset presses perfect. With ink_system uv or led_uv the dry time between passes is always 0.
• Presets. Every value carries {"value", "source", "confidence"}: H the maker's own data, M a secondary source, D derived (with derived_from), G a generic configuration, L unverified. L values are listed in unverified and never copied. A press created from a preset keeps preset_sources.

Send forms (1 to 12) identical forms of sheets sheets each; for offset add passes, plates per form (empty counts CMYK per side), custom_inks and wash_ups; for digital sides and mono. The answer's print object gives makeready, running and wash-up time, plates, impressions, cost and price.

Send forms, sheets per form and strokes per lift. The answer's cut object gives setup, jogging and knife time, lifts, strokes, cost and price.

Finishing machines#

Finishing machines (die-cutters, folder-gluers, flexo folder-gluers, folders, laminators…) have the same list, create, read, update, archive and set-default endpoints under finishing-machines/. The default is per kind: one die-cutter, one folder-gluer and so on. See Finishing machines for what each field does.

• config holds the kind's own settings: a die-cutter's type (platen or rotary, required), stripping, blanking, stripping_setup_min, print_stations, sheet_trim_mm, min_sheet_mm / max_sheet_mm as [width, height]; a folder-gluer's classes ({"straight_line": {}, "crash_lock": {"setup_min": 45, "speed_factor": 0.7}}: a glue style that is absent is not supported) and blank limits; an FFG's stations (required) and setup_min_per_colour; a folder's schemes (a speed factor per fold); a window patcher's speed_by_blank_length ([[longest blank mm, pieces per hour], …], shortest first); a laminator's adhesive_cost_per_m2 and adhesive_price_per_m2. Unknown keys are refused, with the message under config.<key>. Changing kind needs a config valid for the new kind.
• degrade_rules (speed factors, at most 12): {"fact", "op", "value", "speed_factor", "setup_add_min"} with fact one of caliper_in, blank_length_in, pages, thickness_in, gluer, colours; op one of >, >=, <, <=, ==; gluer is compared with == to a glue style.
• speed empty means not set; speed_unit m_per_min is only for folder-gluers, FFGs and label finishers.

Presets return {"kinds": [{"kind", "machines": [...]}]}. They set the kind, the speed unit and technical settings only; rated holds a maker's rated maximum, which a machine created from the preset keeps in preset_sources.rated as a hint. Costs, setup minutes, waste and the planning speed are never in a preset.

Send out (good pieces), optionally setup_key_runs (1 or more: the same setup already ran, so the changeover time applies), feed_in (required for machines in m/min: the piece's length along the feed) and facts (scheme, gluer, colours, stripping, caliper_in, blank_length_in, pages, thickness_in). The answer's step gives units_in, setup_s, run_s, total_s, cost, price and notes (such as speed_unset or degrade_fact_unknown:<fact>).

Tools and rate cards#

Tools (dies, plates, blocks, cylinders and companions) are listed, created, read, updated and archived under tools/; filter the list with tool_type, status and has_layout. A number must be unique in the team. match_key is read-only: it is derived from a box die's dieline, ups and sheet size, or a label die's shape, size, layout and teeth. A die also carries:

• its layout: stations (the station layout, version 1, in mm: kinds, stations with i, kind, x, y, angle, mirrored, the grid, the die rule, board, sheet and die_to_sheet), board_w_in, board_h_in, grain, the whole die's rule (rule_cut_in, rule_crease_in, rule_perf_in, rule_score_in, rule_partial_in, common_line_in), nicks, waste_pieces, stripping, blanking, cut_kind and the read-only source_file_version, kinds (key, design, mirrored, count), ups_total and has_layout. A patched stations must keep each kind's station count; a tool without kinds gets its stations from a die import.
• its links: companion_of (the die a counter, stripper or blanker goes with) and mountable_on (die-cutter ids).
• its lifecycle and ownership: status (on_hand, ordered, repair, retired), ready_at, ordered_at, vendor, po_number, life_impressions, life_left (read-only), last_used_at, history (at most 200 entries of date, kind — rerule, resharpen, repair or note — cost, impressions, note), owner and exclusive.

tools/{id}/layout.svg/ draws the die's stations; tools/{id}/export/?format=cf2|dxf|pdf downloads them as a cut file.

tool-rates/ lists the team's rate cards; POST with a tool_type creates that card (201) or updates the fields you send (200). Rule rates are stored in rule_unit (in or mm) and the area rate in area_unit (in2 or cm2), as sent. See Tools and dies for the formulas and the fields per_up_cost, cad_cost, matrix_cost_per_in, partial_cut_cost_per_in, score_cost_per_in, nick_cost, shipping_cost, minimum_cost, rush_pct, rerule_cost_per_in, wear_cost_per_1000 and board_margin_in.

Die imports#

Post a CF2, DXF or PDF die as file (multipart), or name a Files version with file_version; add format, units (mm or in), mirror (drawn from the die side), mapping ({source key: line kind} over your default profile), overrides ({piece id: "up" | "waste" | "split"}), page (a PDF page, from 0) and tool (the tool a file is attached to). The file is stored in Files first. The answer is the preview: token, file_version, format, units, units_source, board_mm, pages, issues (code, message, detail), sources (each source key with its kind, count and length_mm), ups, grid, rule, waste_pieces, frame, pieces, kinds (per shape: count, measures, svg, existing_design, near_designs, matches with exact and near dies, mirror_of), stations, near_misses, preview_svg and die_cost_estimate. A blocking issue answers 400 with issues, token, file_version, pages, format and sources (the line-type rows when the drawing was read, so a die with no known knife can be mapped): post again with the missing units or mapping. A large file answers 202 with a token; poll die-imports/{token}/ (a token of another team's file answers 404).

die-imports/{token}/save/ saves it: kinds (per shape key, name, family, facts, listed, and use_design to link an existing single-up, new to keep a copy anyway, distinct_from for near duplicates kept apart), tool ({"id": …} attaches the file to that tool; {"create": true, "tool_type", "number", "name", "status", "ready_at", "owner", "customer_name", "exclusive", "sheet_w_in", "sheet_h_in", "die_to_sheet": {"mode": "centre" | "lead", "lead_mm"}, "grain", "stripping", "blanking", "mountable_on"} adds a die), remember_mapping and confirm (a different number of ups than the tool's answers 409 with code ups_changed until confirmed). The answer is 201 with file_version, designs, tool and file_error (null, or Files' error when the file couldn't be moved into the die's folder: the rows are saved and the file stays in Die imports). tool.id must be an active die with stations (400 otherwise). See Importing dies.

Single-up dielines and profiles#

die-designs/ lists single-up dielines (filters family, q, used, listed, include_inactive), each with its measures, size_mm, signature and used_by; one design adds its geometry (version 1, mm, print side), definition, hints and distinct_from. Patch name, family, facts, listed or notes. archive/ answers 409 with in_use while an active die or a part uses it. export/?format=pdf|dxf|cf2|svg downloads it, structure/ returns {structure, scene} for the 3D view (409 with no_structure when it has no panels to fold) and PUT hints/ stores fold hints (version 1; 400 with invalid_fold otherwise). The downloads are the same bytes the Box designer gives. POST distinct/ with {"other": id} records two near-duplicate single-ups as different dies ("Different die: keep separate"): 204, both ways round, so an import never asks about the pair again and matching a design leaves the other out; 400 for the design itself or a design that isn't yours.

line-type-profiles/ keeps how your files name their lines: a name, a format (cf2, dxf, pdf), a mapping of at most 200 source keys and is_default (one default per format; making one the default unsets the other).

tooling-settings/ reads and patches your tooling settings (near_mm must be at least exact_mm; new_die_ups is a list of up to 10 numbers of ups).

Matching dies#

POST tools/match/ answers which of your dies fit something, the way the app's match chips do (Matching jobs to dies). Send exactly one of:

• geometry: a single-up (version 1, mm, y up: outline of at least 3 [x, y] points, holes, and lines by kind: cut, crease, perforation, score, partial_cut; at most 256 KB);
• design: the id of one of your single-up dielines (dies that use that design match at 0 mm);
• definition: a Box designer Definition (a box drawn in the app, at most 4 KB; its shape, then its style and inside size);
• label: {shape, w_in, h_in, r_in} with shape rect, rounded or oval, sizes 0.01 to 200 in and r_in 0 by default (a custom label shape is sent as geometry).

Narrow it with tool_types (dies with stations only; default: all of them; label sizes: the label dies), sheet_in ([w, h], to flag a die laid out for another sheet), die_cutter (a die-cutter's id), customer (the customer's name: another customer's die is listed, not usable), for_imposition (a mirrored fit and a die without stations can't place work) and accepted ({tool, kind, geometry_hash}: a near match the user confirmed; it lapses when geometry_hash differs from the single-up's). The answer is {exact: [...], near: [...]}, near ending with the style-and-size (structural) suggestions; each entry has tool, number, name, kind, tier, dist_mm (null for a style-and-size suggestion), ups, status, ready_at, reasons, usable, confirmed and pose ({x, y, angle, mirrored}). Usable dies come first. Anything but exactly one of the four, an id that isn't yours or a Definition that doesn't validate answers 400.

Every equipment endpoint#