Nest Endpoint
Use the Nest service to pack polygonal parts into available bins. The service mirrors the CLI contract and streams progress via NDJSON.
Endpoint
POST /api/v1/nest
- Authentication: Bearer token
- Headers:
Content-Type: application/json - Response: NDJSON stream of progress, solution, and lifecycle messages.
Search Strategy
- Smart seeding: Sort polygons by descending area so the largest pieces claim space first.
- Guided search: Genetic algorithm mutates placement order and allowed rotations, evaluating collisions and fitness along the way.
- Solution space: With
Npolygons andMrotations each, the theoretical maximum permutations equalN! × M^N. Heuristics prune the search to keep runtimes practical.
Top-Level Configuration
| Key | Type | Default | Notes |
|---|---|---|---|
polygons | array<polyline> | required | Parts to nest. Empty arrays return 422. |
bins | array<bin> | required | Available stock sheets. Must include at least one entry. |
serverId | string | "slow" | Selects a preferred solver queue (slow or fast).
The "slow" server is free to use, but is capped at 30 seconds per request.
The "fast" server is a paid service; see the pricing page for details. |
instances | integer | 1 | Launch this many parallel solvers. Each solver runs on an 2 vCPU cloud server. Parallel jobs share the same payload but explore different random seeds. The best solution across all instances is returned. More than 1 instance is a paid feature. |
minDistance | number | 1.0 | Clearance between parts. Applied as minDistance / 2 offset per polygon. |
curveTolerance | number | 1.0 | Polyline simplification tolerance. Tune alongside minDistance. |
matchingType | string | "solid" | Accepted values: solid, pattern, vertical, horizontal. |
gravityDirection | string | "top" | One of top, right, bottom, left. Drives placement bias and fitness axis. |
xSteps | integer (≥1) | 1 | Splits cellWidth into finer horizontal snapping increments. |
ySteps | integer (≥1) | 1 | Splits cellHeight into finer vertical snapping increments. |
allowedRotations | array<number> | [0.0] | Degrees available to each part. Empty arrays fall back to 0. |
optimization | object | { type: "length" } | Switch between length and area; optional paper size params for area mode. |
populationSize | integer | 10 | Minimum value of 1. Controls genetic algorithm breadth. |
mutationRate | number | 0.1 | Chance of mutating each genome entry per generation. |
reportInterval | number (ms) | 1000 | Zero disables periodic updates. Negative values clamp to zero. |
maximumExecutionTime | number (s) | 300.0 | Clamped to the range (0, 3600]. Hard stop per request. |
Polyline definition
| Key | Type | Default | Description |
|---|---|---|---|
id | string | "" | Identifier forwarded to placement results. |
origin | [x, y] | null | null | Optional placement anchor for pattern matching. Defaults to polyline bounding-box top-left. |
points | array<[x, y]> | [] | Vertices describing closed loops. Winding direction is normalised automatically. |
Coordinates are unit-agnostic. Use a consistent measurement system across polygons, bins, holes, and distances.
Bin Definition
| Key | Type | Default | Description |
|---|---|---|---|
boundary | polyline | required | Outer contour of the sheet. |
holes | array<polyline> | [] | Keep-out zones within the bin. |
cellWidth | number | 0.0 | Native grid spacing along X. Combined with xSteps for snapping. |
cellHeight | number | 0.0 | Native grid spacing along Y. Combined with ySteps. |
In vertical and horizontal matching modes, placements snap to the derived grid. Other modes evaluate multiple
snapped origins per candidate.
Optimisation
| Key | Type | Default | Description |
|---|---|---|---|
type | string | "length" | length minimises span along the active gravity axis; area minimises occupied area. |
params.paperWidth | number | undefined | – | In area mode, estimate sheet utilisation by combining paper width and height. |
params.paperHeight | number | undefined | – | Partner value for paperWidth to compute sheet counts. |
Execution Behaviour
- Requests without
polygonsorbinsreturn validation errors before solving. - All rotations are sourced from
allowedRotations; include every angle you need. minDistanceandcurveToleranceboth affect preprocessing. Increase clearance when you raise the tolerance.maximumExecutionTimecaps runtime per request. Values above one hour clamp to 3600 seconds.reportIntervalgoverns progress cadence. Zero disables periodic updates but the solver still runs at least one generation.
Streaming Messages
Responses are newline-delimited JSON (NDJSON). Each line carries a type key. Clients should parse per-line and tolerate
additional fields as the service evolves.
| Type | When Sent | Additional Fields |
|---|---|---|
progress | Queue notice or periodic solver update. | status, generation, tested, elapsedSeconds, optional queuedPosition. |
solution | First viable placement (generation: 0) and any improvements thereafter. | Includes fitness, usage envelope, placements array, and unplaced ids. |
info | Emitted when the solver hits the time limit. | message, elapsedSeconds. |
done | Always final message after optional info. | None. |
error | Validation or runtime failure. | message describing the failure. |
Example Stream
{"type":"progress","status":"queued","generation":0,"tested":0,"elapsedSeconds":0.0,"queued_position":2}
{"type":"solution","fitness":0.42,"usage":{"width":200.0,"length":300.0,"area":60000.0},"placements":[{"id":"A","position":[10.0,20.0],"rotation":0.0}],"unplaced":[],"generation":0,"elapsedSeconds":0.18}
{"type":"progress","generation":1,"tested":128,"elapsedSeconds":0.92}
{"type":"solution","fitness":0.37,"usage":{"width":195.0,"length":295.0,"area":57525.0},"placements":[...],"unplaced":[],"generation":2,"tested":512,"elapsedSeconds":1.34}
{"type":"done"}