POST /api/v1/solve

The main optimization endpoint. Submit pieces, sheets, and optional strategy/config objects; receive a guillotine layout in a versioned JSON envelope.

Request

POST /api/v1/solve HTTP/1.1
Host: api.cutweaver.io
Content-Type: application/json
X-API-Key: cnw_free_xxxxxxxxxxxxxxxxxxxxxxxx

Representative request body:

{
  "sheets": [
    {
      "width": 3210,
      "height": 2250,
      "quantity": 1,
      "kerfWidth": 4
    }
  ],
  "pieces": [
    {
      "originalIndex": 0,
      "width": 800,
      "height": 600,
      "quantity": 4,
      "canRotate": true
    },
    {
      "originalIndex": 1,
      "width": 1200,
      "height": 900,
      "quantity": 2,
      "canRotate": true
    }
  ],
  "params": {
    "kerfWidth": 4
  },
  "strategy": "greedy"
}

Top-level fields

Field	Type	Required	Notes
pieces	array	yes	Canonical piece list
sheets	array	yes	Canonical stock-sheet list
params	object	no	Global cutting parameters
builderConfig	object	no	Advanced tree-builder tuning
strategy	"greedy" \| "alns"	no	Defaults to "greedy"
alnsConfig	object	no	Used when strategy = "alns"
includeSvg	bool	no	Adds top-level svg array to the response

For the complete field list, see JSON contract.

Response

Representative successful response:

{
  "ok": true,
  "contractVersion": "v1",
  "result": {
    "sheetsUsed": 1,
    "totalPlaced": 6,
    "totalUsedArea": 4080000,
    "totalWasteArea": 3142500,
    "totalUnplacedPriority": 0,
    "unplacedIndices": [],
    "sheets": [
      {
        "sheetIndex": 0,
        "placedCount": 6,
        "usedArea": 4080000,
        "wasteArea": 3142500,
        "largestOffcut": 512000,
        "maxDepth": 6,
        "sheetRotated": false,
        "utilization": 0.56,
        "placements": [
          { "pieceId": 0, "width": 800, "height": 600, "x": 0, "y": 0, "rotated": false }
        ],
        "cutTree": { "type": "cut", "direction": "V", "width": 3210, "height": 2250 }
      }
    ]
  }
}

Notes:

• strategy: "alns" adds a top-level alnsStats object.
• includeSvg: true adds a top-level svg array.
• Very deep trees may be returned as cutTreeFlat instead of nested cutTree.

HTTP status codes

Code	Meaning
200	Layout returned successfully
400	Malformed JSON or invalid schema
401	Invalid API key was provided
413	Payload too large or too many items
415	Request is not application/json
422	Domain validation failed
429	Hosted quota exhausted
500	Unexpected server error

See Errors for the full error catalog.