Skip to content

JSON contract

Single source of truth: docs/CORE_INPUT_OUTPUT_CONTRACT_V1.md in the repo.

This page summarises the contract for HTTP usage. The same JSON works for the C-API (cnw_capi_solve_json) and the WASM build.

Conventions

  • All linear dimensions: integers, millimetres (mm).
  • Areas: integer mm².
  • Coordinates: origin bottom-left, +X right, +Y up.
  • Both snake_case and camelCase are accepted. Documentation uses camelCase.
  • The contract is additive: new fields may appear, existing fields never change meaning.

Request schema

sheets[]

Field Type Required Notes
width int yes mm
height int yes mm
quantity int no default 1
defects[] array no rectangular forbidden zones

pieces[]

Field Type Required Notes
width int yes mm
height int yes mm
quantity int no default 1
rotatable bool no default true
priority int no higher = placed first
grainAxis "x" | "y" | "none" no future, see roadmap

params

Field Type Default Notes
kerf int 0 saw-blade width
marginTop / marginBottom / marginLeft / marginRight int 0 per-sheet edge margins
minOffcut int 0 smallest waste piece worth keeping
maxStages int 3 guillotine cut stages limit

Strategy configs

```json "alnsConfig": { "iterations": 5000, "threads": 4, "seed": 42, "timeBudgetMs": 5000 }

"hpgConfig": { "timeoutMs": 30000, "exact": true } ```

Response schema

Success envelope

json { "ok": true, "contractVersion": "1.0.0", "result": { /* see below */ } }

Error envelope

json { "ok": false, "contractVersion": "1.0.0", "error": { "code": "validation_failed", "message": "..." } }

result.sheets[]

Field Type
index int
width, height int
utilization float [0..1]
placements[] array of placements
svg string (only if includeSvg = true)

result.placements[]

Field Type
pieceId int (index into the request pieces[])
x, y int (mm, origin bottom-left)
width, height int
rotated bool

result.metrics

Field Type
totalUtilization float
wasteRatio float
elapsedMs int
iterations int (ALNS only)