POST /v1/solve¶
The main endpoint. Submit pieces + sheets + params, receive a guillotine layout.
Request¶
http
POST /v1/solve HTTP/1.1
Host: api.cutweaver.io
Content-Type: application/json
X-API-Key: cnw_live_xxxxxxxxxxxxxxxxxxxxxxxx
json
{
"sheets": [ { "width": 3210, "height": 2250, "quantity": 5 } ],
"pieces": [
{ "width": 800, "height": 600, "quantity": 4, "rotatable": true },
{ "width": 1200, "height": 900, "quantity": 2 }
],
"params": {
"kerf": 4,
"marginTop": 10, "marginBottom": 10,
"marginLeft": 10, "marginRight": 10,
"minOffcut": 30
},
"strategy": "alns",
"alnsConfig": { "iterations": 5000, "threads": 4, "seed": 42 },
"includeSvg": false
}
Top-level fields¶
| Field | Type | Required | Notes |
|---|---|---|---|
sheets |
array | yes | at least 1 sheet |
pieces |
array | yes | at least 1 piece |
params |
object | no | kerf, margins, min-offcut, defects |
strategy |
"greedy" | "alns" | "hpg" |
no | default "greedy" |
alnsConfig |
object | no | only used when strategy = "alns" |
hpgConfig |
object | no | only used when strategy = "hpg" |
builderConfig |
object | no | low-level TreeBuilder knobs (advanced) |
includeSvg |
bool | no | embed SVG render in the response |
For exhaustive field-by-field documentation: JSON contract.
Response¶
json
{
"ok": true,
"contractVersion": "1.0.0",
"result": {
"sheets": [
{
"index": 0,
"width": 3210,
"height": 2250,
"utilization": 0.81,
"placements": [
{ "pieceId": 0, "x": 0, "y": 0, "width": 1200, "height": 900, "rotated": false }
]
}
],
"metrics": {
"totalUtilization": 0.81,
"wasteRatio": 0.19,
"elapsedMs": 47
}
}
}
HTTP status codes¶
| Code | Meaning |
|---|---|
| 200 | success, layout returned |
| 400 | malformed JSON or unknown field |
| 401 | missing or invalid API key (when one is required) |
| 413 | payload too large |
| 422 | domain validation failed (e.g., piece bigger than sheet) |
| 429 | quota or rate limit exceeded |
| 500 | internal error — please report |
See Errors for the full error code catalog.