Validate a 2D request
validate_2dFree, no key needed: checks a 2D request without solving it. Same arguments as optimize_2d (field descriptions there). Validate a 2D request — free, no key, no quota, no solve. Schema-validate the SAME body /v1/optimize/2d takes, WITHOUT solving or spending a call. 200 {valid:true, warnings} (warnings flag parts that fit no stock — an approximate, solve-free probe), or 400 with the exact bad field path. Open like /v1/health: validate payloads during integration before you even have a key. The engine verdict matches the optimize path exactly, engine: "max" included: a body this endpoint accepts is one /v1/optimize/2d will accept, and one it refuses (400 for an option the max tier cannot model, 503 where that tier is not enabled) is refused there too.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"parts": "<parts>",
"stock": "<stock>"
},
"name": "validate_2d"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| async | No | Opt in to answers that may arrive later. With `"auto"` a job that finishes within the synchronous time limit still answers 200 with the plan, exactly as without it; a job that would outgrow the limit answers **202** with a `jobId` instead, keeps solving, and its plan is read with `GET /v1/jobs/{id}` (the same poll as engine `max`). The call is billed once, when the plan is written; a solve that fails is not billed. Without this field such a job answers 504 `solve_timeout` with the `jobId` in `details` and is not charged. The official SDKs send it and wait for the job for you. | |
| parts | Yes | The rectangular parts to cut, one row per part type (`w`, `h`, optional `qty`, `name`, grain, edge banding). | |
| stock | Yes | The sheet sizes to cut from, one row per size (`w`, `h`, optional `qty`, `price`). | |
| engine | No | Which optimizer to run. `heuristic` is the guillotine multi-strategy packer: highest yield, every layout edge-to-edge saw-cuttable, always a full `cutPlan`. `balanced` is a MaxRects free-nesting packer: much faster on large jobs for a small yield cost, but its layouts are often not guillotine (`guillotineValid: false`, `cutPlan: null`), and it does not model `tolerance`, `minimizeCost`, `grainGroup`, `maxCutStages` or `minimizeRotations` — set one of those and a string in `warnings` tells you it was ignored. `max` is 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, so instead of a plan it returns **202** with a `jobId` — poll `GET /v1/jobs/{id}` for the result. Still deterministic and guillotine-valid. Where the tier is not enabled on a deployment, `engine: "max"` fails closed with **503**. **What `max` models.** It packs ONE stock format at full sheet size with unlimited supply and a fixed 3-stage guillotine pattern. Anything that would make the returned plan physically WRONG is therefore REFUSED with **400** at submission — before a call is reserved and before you wait for the solve: a second `stock` row, `options.trim`, `options.respectStock`, any `material`, any `grainGroup`, a non-empty `matchedSets` (an empty one is fine). Options that only make the plan less tuned are accepted and listed in `warnings`: `tolerance`, `minimizeCost`, `maxCutStages` (fixed at 3), `minimizeRotations`, `firstCut`, `effort`. A `max` result reports no `offcuts`. Send those jobs to `heuristic`. The default never changes silently. | heuristic |
| include | No | Three kinds of token. NARROWING (`cutPlan`, `offcuts`): omit the field entirely to get both; a present array keeps only the narrowing tokens it lists (an empty array drops both). ADDITIVE EXPORT (`svg`, `csv`, `dxf`): each adds an inline export STRING to the response (`svg` a standalone 2D layout — 2D only, a warning is returned for 1D/wood; `dxf` an R12/AC1009 drawing; `csv` a cut list, RFC 4180 quoted (a part name with a comma or a quote stays one field) and formula-injection-guarded (a name beginning with `=`, `+`, `-`, `@`, TAB or CR is prefixed with an apostrophe so a spreadsheet reads it as text, not a formula — CWE-1236). 2D DATA (`labels`, `planHash`, `pdf`, `labelsPdf`): `labels` adds per-piece label data (`labels[]`, see `Label2D`), `planHash` a 64-hex fingerprint of the plan (the same plan always gives the same hash), `pdf` the cutting-plan PDF and `labelsPdf` the label PDF, both base64-encoded and drawn by the same code as the CutOptim app. These four are 2D only: a 1D or wood request returns a `warnings` entry instead. `pdf` renders at most 500 parts (total quantity); a larger 2D request with `pdf` is a 413 `too_large` with `details.path: "include"`. Export and data tokens do not affect narrowing, so `["svg"]` adds svg and — listing no narrowing token — drops cutPlan/offcuts; use `["cutPlan","offcuts","svg"]` to keep everything. | |
| options | No | Kerf, trim, first-cut direction, cost and stock rules, effort and label output; every field is optional. | |
| matchedSets | No | Matched sets (grain matching): groups of parts cut side by side from one piece of board. Send a NON-EMPTY ARRAY of sets (at most 50); members are named by `parts[].id`. Only a non-empty array switches the feature on: absent, `null`, `[]` — and any value that is not an array — is a request without sets, answered exactly as before (no error). With sets the response adds `sheets[].parts[].matchedSet` on every member and a `matchedSets` rollup; `csv` gains `Set` and `Position` columns at the end, `svg` the `matched-sets` frame group, `dxf` the position code on LABELS; `pdf` and `labelsPdf` draw the members as ordinary parts for now (a `warnings` line says so; the set marks are in `sheets[].parts[].matchedSet`, `csv` and `svg`). Engine `max` refuses a non-empty array (400 `details.unsupported`); an empty one is fine. 2D only: the 1D, wood and nest endpoints ignore this field and `parts[].id`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| parts | Yes | ||
| stock | Yes | ||
| valid | Yes | ||
| warnings | Yes | ||
| engineEnabled | No | ||
| contractVersion | Yes |