timber optimization — 1D with cross-section matching
POST
/v1/optimize/nest
true-shape nesting — irregular polygons on fixed sheets, with exclusion zones (laser / plasma / waterjet)
POST
/v1/validate/2d
validate a request without solving — free, no key, no quota (2d / 1d / wood / nest)
POST
/v1/validate/1d
validate a request without solving — free, no key, no quota (2d / 1d / wood / nest)
POST
/v1/validate/wood
validate a request without solving — free, no key, no quota (2d / 1d / wood / nest)
POST
/v1/validate/nest
validate a request without solving — free, no key, no quota (2d / 1d / wood / nest)
GET
/v1/jobs/{id}
poll an async max-engine job — returns its status and, once finished, the plan (no quota; your own jobs only)
POST
/v1/import/nest
read part outlines out of an SVG or DXF file — needs a key, spends no quota
GET
/v1/usage
the ACCOUNT's current-month usage and quota (all keys share one)
GET
/v1/health
liveness — no key, no rate limit, no database
POST /v1/validate/{2d,1d,wood,nest} — response
valid
boolean
Always true on a 200 — a malformed body is a 400 with the exact bad field path instead. The body is the SAME one the matching optimize endpoint takes.
mode
string
"2d" | "1d" | "wood" | "nest" — the endpoint you called.
contractVersion
string
Shape version. Currently "1".
engineEnabled
boolean
NEST ONLY — whether the nesting engine is built into this deployment. Absent for the rectangular modes.
parts
object
{ rows, total } — part rows sent, and the total quantity after qty expansion. Check it against the part cap before you spend a call.
stock
object
{ rows, total } — the same for stock.
warnings
string[]
Approximate, SOLVE-FREE feasibility notes — e.g. a part that fits no stock (2D and nest: bounding box; wood: no matching section long enough). Empty ⇒ every part fits something. Ignores trim, kerf and material: a shape check, not a solve.
Units
The API is unit-agnostic. Pick one unit — millimetres, inches, anything — use it for every number you send, and every number you get back is in that same unit. Nothing is converted server-side, and no field name asserts a unit.
That covers part and stock dimensions, kerf, tolerance, trim and minOffcut on the way in, and every coordinate, position, remaining length, offcut and cut length on the way out. Mixing units inside one request produces a plan that validates and is physically wrong, and the server cannot detect it.
Coordinate system
The origin is the top-left corner of the sheet: x grows to the right along the sheet width, y grows downward along the sheet height. A part’s x and y are its top-left corner, and its w and h are the dimensions as placed — already swapped when rotated is true — so the rectangle x, y, w, h is the footprint on the board with no further arithmetic. Offcut rectangles use the same system.
Trim moves placements: trim.left shifts every part right and trim.top shifts every part down, because parts are nested inside the usable area and then offset back onto the full sheet. trim.right and trim.bottom shrink the usable area without moving the origin. A sheet’s w and h are always the full stock dimensions, trim included — which is also why trim counts as waste in yieldPct.
default 1 — expanded server-side; counts toward the 2,000 cap
name
optional label, echoed on every placement
rotatable
default true — may the part be turned 90°
grainGroup
members of a group are kept on one sheet (grain matching)
priority
must-cut: wins board space when stock is capped (with respectStock)
edgeBanding
per-edge banding: name a type reference on any of top / right / bottom / left (a free string, your own code) — the response totals the metres by reference. Metadata only, it never moves a part. 2D only
material
material tag (a free string, your own code): parts and stock of the same material are packed only together. Unlike edgeBanding it changes the layout. Absent = one unspecified pool. Works on every mode
Stock fields
w and h are required. qty defaults to 1 and is a hard cap only with respectStock. price is per sheet and drives totalPrice and cost mode. priority (boolean) uses this stock up first; material (a free string) restricts it to parts of the same material.
rank candidates by lowest total stock price; with several priced stock sizes it mixes them (2D) or picks the cheapest length (1D) to minimise the bill, even if that uses more material
respectStock
treat each stock row's qty as a hard cap
minOffcut
only report offcuts whose short side is at least this
maxCutStages
panel-saw stage limit — a phase count, not raw tree depth
minimizeRotations
prefer layouts that turn fewer parts
effort
'fast' | 'balanced' (default 'balanced'). Search depth: 'balanced' runs the full multi-strategy best-of; 'fast' skips the one expensive per-board area-combination search — markedly quicker on large jobs for a few points of yield, still guillotine-valid and never denser than 'balanced'. Small jobs are usually identical. Heuristic engine only
include does two things. NARROWING — "cutPlan" and "offcuts" are on by default; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT — "svg", "csv" and "dxf" each add that export to the response as a STRING: svg a self-contained 2D layout drawing (2D only — a 1d/wood request returns a warning instead), dxf an R12/AC1009 drawing on layers STOCK/PARTS/LABELS, csv a cut list. Export tokens do not affect narrowing, so include:["svg"] adds svg and — naming no narrowing token — drops cutPlan/offcuts; use ["cutPlan","offcuts","svg"] to keep everything and add svg.
Opaque JSON of your own — an ERP article number, an order-line id, a customer ref. Echoed VERBATIM on every placed piece of that part. The optimizer never reads it, so it can never change a layout.
stock[].meta
object
The same on a stock row: echoed on every sheet / rod / nested sheet cut from it, so the plan reconciles with your system without a lookup table.
The effort option trades solve time against yield. Here is that trade, measured on one demanding job — every figure comes from the real packer.
On most (smaller) jobs the two are identical; the gap only opens on large jobs like this one. balanced is the default and is never denser than fast can reach.
And it is fast either way: even the largest production jobs — 2,000 parts and more — solve in single-digit seconds on the default engine, comfortably inside the API time budget.
cutLines vs sawPasses — cutLines merges collinear cuts (one fence setting); sawPasses counts every pass. Two honest measures of the same plan, not a claim to match any competitor’s count.
guillotineValid / cutPlan — When a layout cannot be cut edge-to-edge, guillotineValid is false and cutPlan is null. That is real information — it cannot be made on a panel saw — not an error.
unplaced + warnings — An unsatisfiable job returns 200 with the pieces listed in unplaced and a note in warnings. A plan you can act on beats a status code.
edgeBanding — When any part carries edgeBanding, the response adds an edgeBanding block: the linear metres each type reference consumes, per part and as an order total. It is exact geometry with no waste margin — the workshop adds its own — and it assumes millimetre input (÷1000 for metres). The key is absent entirely for an unbanded job.
materials / unmatchedMaterials — When any part or stock carries material, the response adds materials (a per-material rollup — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) and unmatchedMaterials (demand whose material has no matching stock). On wood the material rides per cross-section section instead. Both keys are absent for a material-free job, which stays byte-identical.
Response fields
Field names and types are the contract, so the tables below stay in English in every language — a translated field name would document an API that does not exist.
POST /v1/optimize/2d — top level
engine
string
Which engine ran: "heuristic", "balanced" or "max".
engineVersion
string
Algorithm identity — package version + a content hash of the algorithm source. Moves automatically on any packer change, and independently per engine.
contractVersion
string
Shape version, matching the /v1/ in the path. Currently "1".
deterministic
boolean
Always true. Present so a client can assert the guarantee it relies on.
sheets
array
One entry per sheet used, in cutting order.
metrics
object
Aggregate numbers for the whole job.
cutPlan
array | null
The sawing plan. null when guillotineValid is false; absent when excluded via include.
unplaced
array
Parts that did not fit, aggregated by name + size. Empty when everything fitted.
warnings
string[]
Free-text notes about the plan. Do not parse — branch on unplaced, guillotineValid and metrics.
guillotineValid
boolean
True when the layout is producible with edge-to-edge cuts, i.e. on a panel saw.
edgeBanding
object
Linear metres of edge banding, grouped by type reference. ABSENT unless a part requested banding via parts[].edgeBanding. 2D only.
materials
array
Per-material rollup. ABSENT unless a part or stock row carried material — a material-free job stays byte-identical. (OPEN-256)
unmatchedMaterials
array
Demand whose material has no matching stock at all. ABSENT when it does not happen. A missing-material report, not a did-not-fit one.
svg
string
Inline SVG of the 2D layout (self-contained, no external refs). Present ONLY when include contains "svg". 2D only. (OPEN-223)
csv
string
Inline CSV cut list. Present ONLY when include contains "csv".
dxf
string
Inline DXF (R12/AC1009) on layers STOCK/PARTS/LABELS. Present ONLY when include contains "dxf".
timing.solveMs
number
Milliseconds inside the packer, 2 decimals. Excludes parsing, auth and queueing.
sheets[]
w, h
number
FULL stock dimensions, trim included — not the usable area.
price
number | null
Price of the stock row this sheet came from, or null if none was given.
parts
array
Placements on this sheet.
offcuts
array
Usable leftover rectangles, filtered by options.minOffcut. Absent (not empty) when excluded via include.
meta
object
Present only when the stock row carried meta — echoed verbatim from stock[].meta. (OPEN-224)
sheets[].parts[]
name
string
The requested name, or the generated default "Part <row>".
x, y
number
Top-left corner of the part, from the top-left corner of the sheet.
w, h
number
Dimensions AS PLACED — already swapped when rotated is true. No client-side swap needed.
rotated
boolean
True if the part was turned 90° from the requested w×h. Informational only.
meta
object
Present only when the part carried meta — echoed verbatim from parts[].meta on every placed piece. (OPEN-224)
sheets[].offcuts[]
x, y, w, h
number
A leftover rectangle, in the same coordinate system as the placements.
metrics (2D)
sheetCount
integer
Sheets used. Equals sheets.length.
yieldPct
number
Placed part area ÷ total FULL sheet area × 100, 2 decimals. Trim and kerf count as waste.
placed
integer
Pieces placed, after qty expansion.
total
integer
Pieces requested, after qty expansion.
cutLines
integer
Collinear cuts merged: same axis, same coordinate, same stage counted once — one fence setting.
sawPasses
integer
Every cut, one per strip crossed — how many separate passes the saw makes.
cutLength
number
Total distance sawn, 3 decimals. Same under either counting convention. In your unit.
totalPrice
number
Sum of the used sheets’ prices, 2 decimals. 0 when no stock row carried a price.
unplaced[] (2D)
name
string
The part name.
w, h
number
As requested.
qty
integer
How many of this part could not be placed.
edgeBanding (2D — present only when a part is banded)
totalMeters
number
Order-wide total across every banded edge, 3 decimals. ⚠️ Assumes mm input: top/bottom edges run the part width, left/right the height, ×qty, ÷1000. In another unit it is your raw edge length ÷ 1000.
byType[]
{ reference, meters }
Order total split by the caller-supplied type reference, sorted by reference.
byPart[]
{ name, meters, byType }
One entry per requested part row that has any banded edge; its byType splits that part’s metres by reference.
cutPlan[]
sheet
integer
0-based index into sheets (2D) or rods (1D). Named sheet in both.
step
integer
1-based order within THIS sheet — it restarts at 1 on every sheet.
axis
"h" | "v"
"h": blade travels along x, separating top from bottom. "v": along y, separating left from right.
pos
number
The blade’s LOW-COORDINATE edge — the y value for "h", the x value for "v" — not its centre line. The kerf occupies pos to pos + kerf.
length
number
Distance the blade travels on this cut: the extent of the region crossed. Always 0 in 1D.
stage
integer
1-based machine pass. Increments only when the axis flips relative to the parent cut.
2D · edgeBanding
When any part carries edgeBanding, the response adds an edgeBanding block: the linear metres each type reference consumes, per part and as an order total. It is exact geometry with no waste margin — the workshop adds its own — and it assumes millimetre input (÷1000 for metres). The key is absent entirely for an unbanded job.
When any part or stock carries material, the response adds materials (a per-material rollup — material, sheetCount/rodCount, yieldPct, placed, total, totalPrice) and unmatchedMaterials (demand whose material has no matching stock). On wood the material rides per cross-section section instead. Both keys are absent for a material-free job, which stays byte-identical.
The tag exactly as you sent it. Free text, matched exactly.
sheetCount | rodCount
integer
Stock consumed for this material — sheetCount on 2D and nest, rodCount on 1D.
yieldPct | density
number
This material’s own fill — yieldPct on the rectangular modes, density on nest (a polygon fill, not comparable to yieldPct).
placed, total
integer
Pieces placed and requested for this material, after qty expansion.
totalPrice
number
Sum of the prices of the stock used for this material.
unmatchedMaterials[] — demand with no matching stock
material
string
The tag that has no stock of its own anywhere in the request.
parts
array
The demand rows in that material, in the mode’s unplaced shape: name, w, h, qty on 2D; name, length, qty on 1D; name, qty on nest.
cutPlan — what one step means physically
A step is one blade movement, and the list is in the order you can actually saw: a parent cut before the cuts inside the piece it produced, because you cannot crosscut a strip before you have ripped it off. axis "h" means the blade travels along x and separates top from bottom; axis "v" means it travels along y and separates left from right. pos is the blade’s LOW-COORDINATE edge — the y value for "h", the x value for "v" — not its centre line: the kerf occupies pos to pos + kerf, so the blade eats in the direction the coordinate grows, which is downward for "h" and to the right for "v". The material on the low side of the line — above it for "h", to its left for "v" — is the piece that cut frees. length is how far the blade travels on that one cut: the extent of the region it crosses, not the width of the whole board.
stage is a machine pass. It starts at 1 and increments only when the axis flips relative to the parent cut, so ripping a board into six strips is one stage and crosscutting them is the next. That is the panel-saw sense of “three-stage cutting”, not the depth of the cut tree, and it is what maxCutStages constrains. sheet is a 0-based index into sheets, and step restarts at 1 on every sheet instead of running across the whole job.
cutPlan is null — not missing, not empty — whenever guillotineValid is false: a layout that cannot be cut edge to edge has no cut sequence to return. It is absent from the payload altogether if you left it out of include.
Parts take length (plus qty, name, priority); stock takes length, qty and price. Both parts and stock also accept an optional material tag (stock also priority) — material restricts a part to stock of the same material, and the response then adds materials and unmatchedMaterials as in 2D. Options are kerf, tolerance, trim.start / trim.end, minimizeCost, respectStock and minOffcut. The response returns rods instead of sheets, each with its parts, remaining length and offcuts.
rods replaces sheets and there is no guillotineValid, because a linear cut is always producible. Each part’s pos is the offset of its near end from the bar end that trim.start trims, so the first part starts exactly at trim.start and each following pos adds one kerf. remaining is the USABLE off-cut: the kerf of the cut that frees it from the last piece is already deducted, so it is the reclaimable length, not the raw gap. It is reported on every rod even when it is below minOffcut — minOffcut only filters the offcuts array, which holds at most one entry. In the cut plan, sheet is the rod index, axis is always "v", stage is always 1 and length is always 0: a bar crosscut has no travel distance to report, which is also why the 1D metrics carry cuts but no cutLength.
Timber has an identity a plain bar does not: a 50×150 part cannot come out of 50×100 stock, however much length is left. Parts and stock therefore carry sw and sh, the two cross-section sides, in either order — 50×100 and 100×50 are the same bar turned over and are matched as one section. The job is split by cross-section, each section is matched to its own stock and solved on its own, and one call returns the whole thing. Parts and stock also accept an optional material tag (stock also priority): with it, an oak 50×100 and a pine 50×100 become two separate sections, and each section carries its material. Options are the same as 1D.
sections replaces rods at the top level: each entry is one cross-section with its own rods (identical in shape to 1D) and its own metrics, so the per-material figures are there without recomputing them. unmatched has no 1D equivalent — it is demand whose cross-section you supplied no stock for at all, which is a different problem from unplaced (parts that had stock and did not fit) and has a different fix, so the two are never mixed. metrics.total counts every piece you asked for, unmatched ones included. In the cut plan each step also names its section, and sheet is the rod index WITHIN that section rather than a job-wide counter.
POST /v1/optimize/wood — top level (what differs from 1D)
sections
array
Replaces rods at the top level: one entry per cross-section, each matched to its own stock and solved on its own.
unmatched
array
Demand whose cross-section has NO stock at all. Deliberately separate from unplaced (had stock, did not fit) — the fix differs, so the two are never mixed.
unplaced
array
Did-not-fit demand, aggregated across the sections that DID have stock. Same shape as 1D.
metrics
object
Job-wide totals across every section (below).
cutPlan
array | null
As 1D, except every step also carries section, and sheet is the rod index WITHIN that section, not a job-wide counter.
csv, dxf
string
Inline export, present only when include names the token. svg is 2D-only — a wood request asking for it gets a warning instead.
sections[]
section
string
Normalised cross-section key, e.g. "50x100" — short side first, so 50×100 and 100×50 are one section.
sw, sh
number
The two cross-section sides: sw the SHORT one, sh the long one, whatever order they arrived in.
stockName
string | null
The name of the stock row this section was matched to, or null when that row carried none.
material
string
Present only when the section carries a material — an oak 50×100 and a pine 50×100 are two sections. (OPEN-256)
rods
array
Identical in shape to the 1D rods[] above, meta and offcuts included.
metrics
object
This section’s own totals: rodCount, yieldPct, placed, total, cuts, totalPrice — so the per-section figures need no recomputation.
unplaced
array
This section’s parts that had stock and still did not fit.
metrics (wood)
sectionCount
integer
Cross-sections solved. Equals sections.length.
rodCount
integer
Bars used across every section.
yieldPct
number
Placed length ÷ total FULL bar length × 100 over the whole job, 2 decimals.
placed
integer
Pieces placed, after qty expansion.
total
integer
Pieces REQUESTED, after qty expansion — unmatched ones included.
cuts
integer
Crosscuts across every used bar.
totalPrice
number
Sum of the used bars’ prices, 2 decimals.
toleranceAcceptedCount
integer
Pieces that fitted only because options.tolerance allowed an overshoot.
unmatched[]
section
string
The cross-section key nothing in stock matched.
sw, sh
number
That cross-section’s two sides.
material
string
Present when the cross-section DOES exist in stock but only in a different material. (OPEN-256)
parts
array
The demand rows in that section, in the 1D unplaced shape: name, length, qty.
qty
integer
Total pieces in this section that had no stock at all.
The three modes above pack rectangles. POST /v1/optimize/nest packs ARBITRARY POLYGONS: a part is an outline (polygon, with optional interior holes), not a width×height, so parts interlock into each other’s concave pockets and the notch-air a bounding box wastes is reclaimed — on a representative job, 6 sheets where the same parts by bounding box need 9. It is a different class of algorithm (a geometric collision engine, not the guillotine packer), for laser, plasma and waterjet cutting. Two things the rectangular API cannot express come with it: per-sheet exclusion zones (stock[].exclusions — a defect, a clamp footprint, a pre-printed area; a quality-0 zone is a no-go region for any part) and true-shape holes. material partition and the meta passthrough work as everywhere else. The example below is one real captured call — eight parts on a single sheet with a damaged corner excluded.
POST /v1/optimize/nest — request (top level)
parts
array
One or more NestPart (see below). Required.
stock
array
One or more NestStock sheet types (see below). Required.
options
object
Solve options (see below). Optional.
engine
string
"lbf" (default, single-pass, instant) or "sparrow" (advertised for a future higher-density build; currently served by lbf with a warning).
include
string[]
Additive inline export of the ACHIEVED nest: "svg" a self-contained styled drawing (one titled band per sheet, parts as filled polygons with holes, exclusion zones hatched), "dxf" an R12/AC1009 document on layers STOCK/PARTS/HOLES/ZONES/LABELS. Unit-agnostic, exactly like the request coordinates. The geometry in sheets[] is returned either way.
parts[] (NestPart)
polygon
number[][]
The part outline: an ordered ring of ≥3 [x, y] vertices. Given closed (first == last) or open; winding order is not required — it is oriented internally. Required UNLESS the row carries source.
source
object
OPEN-262 — read the outline out of an SVG or DXF FILE instead of listing coordinates (fields below). EXACTLY ONE of polygon / source: both, or neither, is a 400.
holes
number[][][]
Optional interior holes — a part with a cut-out. Each hole is a ring like polygon. NOT accepted alongside source: the file already carries its own holes, and two sources of truth for one geometry is not a thing we resolve silently.
qty
integer
Copies to place. Default 1.
allowedRotations
number[] | "continuous"
Allowed rotations in DEGREES (e.g. [0,90,180,270]). Omit or "continuous" for free rotation.
minQuality
integer
The part may only be placed where sheet quality ≥ this. Default 1 → it avoids every quality-0 exclusion zone. Raise it to keep the part off inferior-but-not-forbidden zones too.
priority
boolean
Must-cut: wins sheet space when stock is capped (options.respectStock).
material
string
OPEN-256 — a part of material X nests only on material-X sheets; the job is partitioned by material.
name
string
Optional label, echoed on every placement. Defaults to "Part <1-based row index>".
meta
object
OPEN-224 — opaque JSON (your ERP ids), echoed verbatim on every placed copy. Never affects the layout.
stock[] (NestStock)
w, h
number
Rectangular sheet size. Give w & h OR polygon, not both.
Default 1. A HARD cap only when options.respectStock is true.
price
number
Per-sheet price, for cost mode + totalPrice.
exclusions
object[]
OPEN-233 — per-sheet excluded / inferior zones. Each: { polygon: number[][], quality?: integer }. quality 0 (the default) = a hard no-go region for any part; a higher quality only excludes parts whose minQuality demands at least that. This is what the rectangular API cannot express.
material
string
OPEN-256 — this sheet serves only material-matching parts.
meta
object
OPEN-224 — echoed on every sheet cut from this stock row.
options (NestOptions)
minSeparation
number
Minimum clearance between parts and between a part and any hazard (sheet edge / exclusion zone). Use for kerf / beam / torch width. Default 0.
seed
integer
Determinism: a fixed seed → a reproducible layout. Omit and the server pins a fixed default so the response stays reproducible.
minimizeCost
boolean
Rank plans by total sheet price rather than sheet count.
respectStock
boolean
Treat each stock qty as a hard cap.
simplifyTolerance
number
Polygon simplification tolerance (max area deviation as a fraction). Speeds up dense DXF outlines with hundreds of vertices. 0 disables.
timeBudgetMs
integer
Wall-clock budget for the metaheuristic (engine "sparrow"). Ignored by "lbf" (single-pass).
Each entry in sheets is one used sheet; a placed part carries the rigid transform (rotation in degrees, then x/y translation), NOT a re-emitted polygon — rotate your input outline by rotation about its origin and add (x, y) to reconstruct the placement exactly. rotation may be negative; the reconstruction is exact regardless of sign. ⚠️ density is the placed POLYGON area over used sheet area — the honest fill, with concave pockets counted as empty — and is NOT comparable to a rectangular packer’s yieldPct (which counts each bounding box as solid, so it reads higher for a worse result); the cross-comparable metric across the two is sheetCount on the same parts. The layout is deterministic: set options.seed to reproduce it. exclusions is echoed on each sheet for rendering. Ask for include:["svg","dxf"] and the response also carries a self-contained SVG drawing and an R12 DXF of the achieved nest, inline.
POST /v1/optimize/nest — top level
engine
string
Which nesting engine ran: "lbf" or "sparrow".
engineVersion
string
The nesting engine's algorithm identity (jagua-rs revision + build hash). Versions independently of the rectangular engines.
contractVersion
string
Nest contract version, currently "1". Versions independently of the /v1/ rectangular contract — it is a different path and engine family.
deterministic
boolean
Always true — guaranteed by the pinned seed.
sheets
array
One entry per used sheet.
metrics
object
Job totals (see below).
unplaced
array
Demand that could not be placed — a plan-plus-warning, not an error.
warnings
string[]
e.g. an engine substitution ("sparrow" served by "lbf"), unplaced parts, or a material with no matching stock.
materials
array
OPEN-256 per-material rollup — present only when parts/stock carry material.
unmatchedMaterials
array
Parts whose material has no matching stock — present only when it happens.
imported
object
OPEN-262 — what the request’s source files contributed (fields above). ABSENT for a coordinates-only job, which is what keeps such a request byte-identical to before the feature existed.
svg, dxf
string
The achieved nest as an inline drawing — present ONLY when include contains that token. svg is self-contained (no external refs); dxf is R12/AC1009.
timing
object
{ solveMs: number } — the solve time; environment-dependent.
sheets[] (nest)
w, h
number
Present for rectangular sheets.
polygon
number[][]
Present for arbitrary-outline sheets instead of w/h.
price
number | null
The stock row's price, or null.
density
number
This sheet's fill = placed polygon area / sheet area.
parts
array
Placements on this sheet (see below).
exclusions
object[]
The zones that applied to this sheet, echoed for rendering.
material
string
Present when the sheet carried a material (OPEN-256).
meta
object
Echoed from the stock row's meta (OPEN-224).
sheets[].parts[] (nest — placed)
name
string
The requested name, or the generated default.
sheet
integer
0-based index into sheets.
x, y
number
Translation, applied AFTER rotation about the part's origin.
rotation
number
⚠️ Degrees, applied about the part's own origin FIRST. A placed part carries this rigid transform, NOT a re-emitted polygon: rotate your input outline by rotation, then add (x, y) to reconstruct the placement exactly. May be negative; the reconstruction is exact regardless of sign.
material
string
The material this copy nested from (OPEN-256).
meta
object
The part's opaque passthrough (OPEN-224).
metrics (nest)
sheetCount
integer
Sheets used. Equals sheets.length. ⚠️ The honest, cross-comparable metric between nesting and the rectangular modes.
density
number
⚠️ Placed POLYGON area / used sheet area — the honest fill (concave pockets count as empty). NOT comparable to a rectangular packer's yieldPct, which counts each bounding box as solid and so reads higher for a worse result.
placed
integer
Part copies placed, after qty expansion.
total
integer
Part copies requested, after qty expansion.
totalPrice
number
Sum of used sheet prices.
unplaced[] (nest)
name
string
The part name.
qty
integer
How many copies could not be placed.
rods[]
length
number
FULL bar length as supplied in stock.
price
number | null
Price of the stock row, or null.
remaining
number
USABLE off-cut left on this bar, 3 decimals — the kerf of the cut that frees it from the last piece is already deducted (OPEN-257), so it is the reclaimable length, not the raw gap. Reported even when below minOffcut.
parts
array
Placements, in cutting order along the bar.
offcuts
number[]
At most one entry: [remaining] (the kerf-corrected usable off-cut, OPEN-257) when it is > 0 and ≥ minOffcut, else []. Absent when excluded via include.
meta
object
Present only when the stock row carried meta — echoed from stock[].meta (OPEN-224). Applies to 1D and wood rods.
rods[].parts[]
name
string
The requested name, or the generated default.
pos
number
Offset of the part’s NEAR end from the bar end that trim.start trims.
length
number
The part length, as requested.
meta
object
Present only when the part carried meta — echoed from parts[].meta (OPEN-224).
metrics (1D)
rodCount
integer
Bars used. Equals rods.length.
yieldPct
number
Placed length ÷ total FULL bar length × 100, 2 decimals. Trim and kerf count as waste.
placed
integer
Pieces placed, after qty expansion.
total
integer
Pieces requested, after qty expansion.
cuts
integer
Total crosscuts across all used bars — one per placed piece.
totalPrice
number
Sum of used bar prices, 2 decimals.
toleranceAcceptedCount
integer
Pieces that fitted only because options.tolerance allowed an overshoot.
unplaced[] (1D)
name
string
The part name.
length
number
As requested.
qty
integer
How many could not be placed.
Parts from a file (SVG · DXF)
A part does not have to arrive as coordinates. Put an SVG or DXF document in parts[].source and the server reads the outline — and its holes — out of it with the same parser the CutOptim app uses when you drop a drawing on its Nesting mode. The file replaces ONLY the geometry: qty, material, allowedRotations, minQuality, priority and meta behave exactly as they do on a polygon part, so a part library that already exists as CAD files needs no path-and-arc flattener of your own. One source describes ONE part; a drawing holding several separate components is a 400 that points you at the import endpoint below. The response then carries an imported block saying how many rows came from a file, how many vertices they produced, and which units those files declared — reported, never applied, because this API converts nothing.
Nothing is stored. The bytes exist only as the request body, are parsed in memory, and are gone when the response is written: no disk, no database, no temporary file, no log line. There is nothing to delete afterwards and nothing retained — the same statelessness every other endpoint keeps.
Field names and types are the contract, so the tables below stay in English in every language — a translated field name would document an API that does not exist.
The file TEXT — not base64, not a URL, not a multipart upload. Both formats are text documents, so they travel inside the JSON body like any other field. At most 4,000,000 characters per file and 8,000,000 across one request; over either is a 413.
format
"svg" | "dxf"
Omit and the server sniffs the content (an <svg tag ⇒ svg, otherwise dxf). An explicit value ALWAYS wins — including over a filename whose extension disagrees, which is the case worth setting it for.
filename
string
Used for format detection AND as the part name when the row has no name of its own (extension stripped). It never touches a filesystem — there is no file on our side to name.
flattenTolerance
number
Curve and arc flattening tolerance, in the FILE’s own coordinate unit. Default 0.2. Larger = fewer vertices; this is the lever when a dense outline trips the 2,000-vertex per-ring cap.
imported — what the files contributed (response, absent without a source)
parts
integer
Part ROWS whose geometry came from a file.
vertices
integer
Total vertices those files produced after flattening, outlines and holes together — the number to watch against the per-ring cap.
units
string[]
⚠️ Units the files DECLARED (a DXF $INSUNITS), not units we applied. Empty when none declared one. More than one entry also raises a warning: mixing a millimetre drawing with an inch one produces a plan that validates and is physically wrong, and the server must not "fix" that by converting — no field in this API asserts a unit.
POST /v1/import/nest — one file, every outline
When a single drawing holds several different parts, import it first: this endpoint returns every closed outline it contains, largest first, in exactly the shape a parts[] row wants. Paste in the ones you need, add your own qty and material, and post that to /v1/optimize/nest. It is also how you see what is in a file before spending a solve on it. It needs a key — flattening arbitrary geometry is real CPU work, and anonymous CPU is a bad trade — but it reserves nothing: your quota is untouched and no rate-limit headers come back, exactly like polling a job.
The file text. Required. Same 4,000,000-character cap as parts[].source.
format
"svg" | "dxf"
Omit to sniff; an explicit value wins over the filename extension.
filename
string
Used for detection and to NAME the results: a file with one outline keeps the bare name, several are numbered "<name> 1", "<name> 2", …
flattenTolerance
number
As on parts[].source. Default 0.2.
POST /v1/import/nest — response
format
"svg" | "dxf"
The parser that actually ran — the useful bit when you let the server sniff.
parts[]
{ name, polygon, holes? }
One entry per closed outline, LARGEST FIRST. Each is already in the shape a parts[] row wants: paste it in and add your own qty / material / allowedRotations. Deterministic — the same bytes always give the same vertices in the same order.
vertices
integer
Total vertices after flattening. Compare it against the 2,000-per-ring cap before you build a large request.
sourceUnit
"mm" | "in"
A DXF $INSUNITS declaration, when the file carries one. REPORTED, NEVER APPLIED. Absent for SVG (the format has no unit) and for a DXF that declares none.
warnings
string[]
What the parser could not honour — an SVG transform= attribute (CAD part exports are flat, so we do not apply them), or geometry that never closed into a contour. Empty means the file was read whole.
engineEnabled
boolean
Whether THIS deployment can also SOLVE a nest. Importing is pure parsing and works everywhere; where the nesting engine is not built in, /v1/optimize/nest answers 503 and this flag says so up front. Same field /v1/validate/nest carries.
contractVersion
string
Nest contract version. Currently "1".
Engines
heuristic(default) — the guillotine multi-strategy packer. Highest yield, every layout saw-cuttable, always a full cutPlan.
balanced — a MaxRects free-nesting packer. Much faster on large jobs (measured ~25× at 2,000 parts) for a small yield cost, and its layouts are often not guillotine (guillotineValid: false, cutPlan: null). It does not model tolerance, minimizeCost, grainGroup, maxCutStages or minimizeRotations — set one and a warning tells you it was ignored.
max — the asynchronous tree-search tier (2D only): it reaches the proven optimum on far more jobs at the cost of seconds-to-a-minute per solve. Still deterministic and guillotine-valid. It does not return a plan directly — see Async jobs below. It models ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern, so a second stock row, trim, respectStock, material or grainGroup is refused with 400 before a call is reserved; tolerance, minimizeCost, maxCutStages, minimizeRotations, firstCut and effort go through but are ignored with a warning, and a max result reports no offcuts. Send those jobs to heuristic.
Async jobs (engine = max)
A max solve takes seconds to a minute, so POST /v1/optimize/2d with engine:"max" does not return a plan — it returns 202 Accepted with a jobId, and the call is metered at submission. Poll GET /v1/jobs/{id} until status is "succeeded" (result holds the same 2D response a synchronous solve returns) or "failed" (error holds the message). Polling spends no quota; you see only your own jobs. Where the tier is not enabled on a deployment, engine:"max" fails closed with 503.
field
type
meaning
jobId
string
The 202 body's id. Poll GET /v1/jobs/{id}.
status
string
queued → running → succeeded | failed.
mode · engine
string
Always "2d" and "max".
pollAfterMs
integer
202 only — suggested delay before the first poll.
result
object
Present once succeeded — the same shape as a synchronous 2D response.
error
string
Present once failed — the reason.
quota
object
202 only — reserved, used and limit: the one call metered at submission, and where the ACCOUNT stands this month.
createdAt
string
Poll only — when the job was submitted (ISO-8601).
finishedAt
string | null
Poll only — when the worker finished; null while queued or running.
Determinism & versioning
Every response carries engineVersion. The algorithm is deterministic, so improving it changes output for the same input — which is a breaking change if you cache. Pin behaviour by sending engine explicitly and watching engineVersion; the path version /v1/ only changes if the response shape changes.
Each engine versions independently, so a change to one never moves the other's version.
Errors
400
invalid_request
Schema error. details.path points at the offending field.
401
unauthorized
Missing or unknown API key.
402
quota_exceeded
Monthly quota reached. Retry-After gives the seconds until the month rolls over.
403
key_revoked
The key exists but may not be used: it has been revoked, or the account Engine API subscription is no longer active. The message says which.
404
not_found
No such route — also what you get for the right path with the wrong method.
413
too_large
Input above a limit (see Limits).
429
busy
Momentarily at capacity. Retry-After in seconds — this never counts against your quota.
500
internal
Unexpected error, or the auth backend is unreachable (requests fail closed).
503
service_unavailable
An engine you asked for cannot be served right now — the nesting engine, or the async max engine. Two causes for max, and the message says which: the tier is not built into this deployment, or it is built in but the worker that solves the jobs is not responding. Fail-closed before a call is reserved, so it never costs you anything.
504
solve_timeout
The solve exceeded its hard time bound. On the rectangular paths the proxy enforces it; on /v1/optimize/nest the engine enforces its own, shorter budget and answers solve_timeout in the normal envelope.
Error body
Every error the engine itself produces uses the same envelope. Branch on error, which is a stable code; never on message, whose wording can change between releases. details is present on invalid_request, where path names the offending field, and on too_large, where max and got give the cap and what you sent.
HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
"error": "invalid_request",
"message": "parts[0].h: must be greater than 0",
"details": { "path": "parts[0].h" }
}
402 and 429 both carry a Retry-After header in seconds. On 402 it counts down to the quota reset at 00:00 UTC on the 1st of next month; on 429 it is a short back-off, and a 429 never consumes quota — the reserved call is handed back.
A routing failure answers with not_found, a code deliberately outside the list above because the router produces it rather than the API contract. You get 404 and not 405 when the path is right but the method is wrong: all four optimize endpoints are POST-only.
On the rectangular paths 504 comes from the reverse proxy, not from the engine, so its body belongs to the proxy and is not this JSON envelope; within the input limits below it should be unreachable. /v1/optimize/nest is the exception: that solve is a subprocess with its own budget, deliberately kept below the proxy bound, so a timeout there does use this envelope, with the code solve_timeout.
Rate-limit headers
A successful optimize call carries X-RateLimit-Limit (the ACCOUNT’s monthly cap — every key on the account shares one) and X-RateLimit-Remaining (calls left this month on the account, after this one). They are sent by the optimize endpoints only: the counter is reserved as part of authorizing a solve, so /v1/usage and /v1/health have nothing to report.
X-RateLimit-Limit
integer
The ACCOUNT’s monthly quota — the same number GET /v1/usage returns as limit, not a per-key cap (049).
X-RateLimit-Remaining
integer
Calls left this month on the ACCOUNT, after this one.
Read-only: it does not consume a call and sends no rate-limit headers. ⚠️ used and limit describe the ACCOUNT, not the key you called with: every active key on the account draws on one shared allowance, so creating more keys does not create more quota. used counts the current UTC calendar month across all of them, remaining is limit minus used and never goes negative, periodEnd is the reset day as a plain YYYY-MM-DD date, and keyPrefix is the non-secret display prefix of the key you called with. The key itself is never returned by any endpoint — only its hash is stored, so a lost key is replaced, not recovered.
plan
string
Tier slug frozen onto the key when it was created.
used
integer
Calls counted in the current UTC calendar month across EVERY key on the ACCOUNT — revoked keys included, so revoking a key cannot un-spend what it spent (053).
limit
integer
The ACCOUNT’s cap: the largest monthly quota frozen onto any of its ACTIVE keys (049). Not a per-key allowance — more keys do not add quota.
remaining
integer
limit − used, never negative.
periodEnd
string
Reset day as YYYY-MM-DD — a date, not a timestamp.
No key, no quota, no database. It deliberately touches nothing stateful, so an outage in the key store cannot make the service look dead to an orchestrator. engines lists the ids this deployment accepts in engine, and engineVersion is the default engine’s version.
status
string
Always "healthy" when the process answers.
service
string
Always "cutoptim-engine".
contractVersion
string
Shape version. Currently "1".
engineVersion
string
The DEFAULT engine’s version, not a per-engine list.
engines
string[]
SYNCHRONOUS engine ids this deployment accepts in engine — ["heuristic","balanced"]. The async max tier is reported separately in maxEngines, never here.
modes
string[]
Optimize paths this deployment serves: "2d", "1d", "wood", plus "nest" only where the nesting engine is built in. Endpoint discovery without reading this page.
nestEngines
string[]
Nesting engine ids this deployment can serve — ["lbf"] on the production API, [] where the Rust nesting stage is not built in.
maxEngines
string[]
The async tree-search tier — ["max"] where it is enabled, [] otherwise. Health never advertises a capability it cannot serve.
uptimeSec
integer
Whole seconds since process start.
Limits
2,000 parts per request (total quantity, after qty expansion)
50 stock rows · request body up to 1 MB
10 active keys per account — they share ONE monthly quota, so keys separate environments and integrations, they do not add allowance
10 MB request body on the two nest paths that may carry a drawing (/v1/optimize/nest and /v1/import/nest); one source file is at most 4,000,000 characters, 8,000,000 across a request
concurrency is bounded server-side — a burst gets 429, never a slow queue. The keyless validate endpoints additionally have a per-address ceiling (429 with Retry-After); a key is never throttled that way. An account may hold 5 max jobs queued or running at once.
OpenAPI specification
A machine-readable OpenAPI 3.1 document describes all twelve endpoints, every request body, every response shape and every error. Point your client generator at it instead of transcribing this page. The document itself is English only: it is made of contract tokens, and OpenAPI has no localization mechanism.
A two-page summary of the Engine API — the four modes (2D, 1D, wood and true-shape nest), a request and response, determinism and pricing. Print-ready, with a QR back to the docs.