--- title: "Optimise a cut list: pieces from stock lengths, or rectangles nested on sheets" method: POST path: "/optimise-cuts" tags: ["Calculators"] --- # Optimise a cut list: pieces from stock lengths, or rectangles nested on sheets `POST /optimise-cuts` ## Request - Base URL: `https://api.craftquantities.com/v1` - URL: `https://api.craftquantities.com/v1/optimise-cuts` - Auth: none declared Stateless: the cut list arrives and the plan goes back. The site's own optimiser, as its cut-list tool and the Construction Canvas run it. ## Query parameters - `detail` 'full' | 'summary': full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read. - `format` 'json' | 'md' ## Request body - object - `kind` 'linear' | 'sheet', required: linear: lengths cut from stock lengths (studs, plates, joists, rafters, bars, trim, boards). sheet: rectangles nested on sheets (plasterboard or drywall, plywood, OSB, tiles). - `material` 'timber' | 'rebar' | 'casing' | 'plasterboard' | 'plywood' | 'osb' | 'tile': What is cut, for the market's stock lengths or sheet sizes, saw kerf and grain when they are left out: timber (the default for linear), rebar or casing; plasterboard (the default for sheet), plywood, OSB or tile. - `pieces` object[], required: The cut list: up to 200 lines and 3000 pieces (1500 for sheets) in all. - `length` union: linear: the finished length, with its unit. - number - string - object - `value` number, required - `unit` string - `width` union: sheet: the piece's width, with its unit. - number - string - object - `value` number, required - `unit` string - `height` union: sheet: the piece's height (along the grain), with its unit. - number - string - object - `value` number, required - `unit` string - `count` integer, required - `label` string - `join` boolean: linear: a run that may be joined where a stock length runs out (a plate, a rim, trim, a board run). Left out, a piece longer than every stock length is listed, not split: a joint in a joist, a rafter or a bar is the designer's. - `rotate` boolean: sheet: whether this piece may turn a quarter; left out, as the request says. - `stock` union[]: linear: the stock lengths on offer, each in any number, with units ("4.8 m", "16 ft"). Left out, the market's usual lengths for the material in the system asked for. - union - number - string - object - `value` number, required - `unit` string - `sheets` object[]: sheet: the sheet sizes on offer (the plan takes the one that buys the least area). Left out, the market's usual size for the material. - `width` union, required - number - string - object - `value` number, required - `unit` string - `height` union, required - number - string - object - `value` number, required - `unit` string - `kerf` union: The saw's kerf, charged on every piece (both ways on a sheet). Left out, the material's: 3 mm or 1/8 in for a saw, none for a bar shear or a board knife. - number - string - object - `value` number, required - `unit` string - `minOffcut` union: linear: the shortest offcut worth keeping; shorter ones count as waste. - number - string - object - `value` number, required - `unit` string - `rotate` boolean: sheet: whether pieces may turn a quarter (no grain or strength axis to keep). Left out: yes for plasterboard and tiles, no for plywood and OSB. - `system` 'metric' | 'imperial': The unit system inputs left out open in, and the one the page link opens in. The answer comes in both. - `inputUnits` 'base': Send "base" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit. ## Response `200` What to buy, the cutting plan, the waste and the bound. - union - object - `engine` object, required - `system` 'metric' | 'imperial', required - `kind` 'linear' | 'sheet', required - `material` string, required - `given` object, required: What the plan was worked from, in both systems: the stock lengths or sheet sizes, the kerf, the minimum offcut, whether pieces turn. - `buy` object[], required: What to buy: each stock length or the sheet size, and how many. - `count` integer, required - `stock` object - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - `sheet` object - `text` string, required - `pieces` integer - `bought` union - object - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - object - `m2` number, required - `ft2` number, required - `text` string, required - `required` union - object - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - object - `m2` number, required - `ft2` number, required - `text` string, required - `waste` object, required - `percent` number, required - `excludingKeptOffcutsPercent` number - `keptOffcut` object - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - `bound` object, required: The floor no plan can beat: the pieces with their kerf over the stock (with one stock length, at least one bar for each piece over half a bar; on sheets, one sheet for each piece too big to share one). - `gapPercent` number: How far this plan is above the bound, percent. - `proven` boolean, required: True when no plan buys less: the exact branch and bound finished, or the plan meets the bound. - `patterns` union[], required: Each way a bar or sheet is cut, with how many are cut that way; up to 150, most used first. - union - object - `times` integer, required - `stock` object, required - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - `cuts` object[], required - `length` object, required - … - `label` string - `joined` boolean - `offcut` object, required - `m` number, required - `ft` number, required - `text` string, required: In the system asked for, then the other. - `keep` boolean, required - object - `times` integer, required - `placed` object[], required - `x` object, required - … - `y` object, required - … - `width` object, required - … - `height` object, required - … - `rotated` boolean, required - `label` string - `largestOffcut` object - `patternsTotal` integer, required - `tooLong` object[]: Pieces no stock length or sheet takes, listed rather than split. - `joinedRuns` integer - `steps` integer: Search steps spent (bounded). - `method` string[], required - `notDesign` string, required - `citation` object, required - `author` string, required - `title` string, required - `version` string, nullable - `sourcesChecked` string, nullable - `url` string, required - `accessDate` string, nullable, required - `formats` object, required - `plain` string, required - `apa` string, required - `harvard` string, required - `bibtex` string, required - `licence` object, required - `name` string, required - `url` string, required - `attribution` string, required - `notice` string, required - `links` object, required - `page` string, required - object - `detail` 'summary', required - `tool` string, required - `title` string, required - `lines` object[], required: The result lines, as the report's table gives them. - `notes` string[], required: What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary. - `citation` string, required: The one citation line, built from the answer's own data. - `url` string, nullable, required - `open` string, nullable, required - `more` string, nullable, required ## Other responses - `400`: The request was refused; every problem is listed. --- [API](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api.md) · [All operations](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/revisions/a69883abc23b?raw)