True-shape nesting

A nest places irregular parts on sheets, holes and spacing included, and searches for a while to do it well. So it runs in the background: POST /v1/nests queues it and answers at once with a job; you poll the job until it is done, then read the plan and its exports. Nesting needs the Bench plan or above.

Start a nest

curl https://api.nestsolver.com/v1/nests \
  -H "Authorization: Bearer $NESTSOLVER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "mm",
    "part_spacing": "5",
    "edge_spacing": "10",
    "target": "fewest",
    "strict": false,
    "sheets": [{ "width": "3000", "height": "1500", "quantity": "" }],
    "library": { "0192e3b1-4c5d-7e6f-9a0b-1c2d3e4f5a6b": { "quantity": "12", "rotation": "any" } },
    "typed": [{ "kind": "circle", "diameter": "120", "quantity": "8", "label": "Flange", "rotation": "any" }],
    "remnants": []
  }'

Field	Meaning
unit	mm, cm, m or in.
part_spacing	The gap kept between parts, for the cut's width and the heat it spreads. It holds inside holes too: a part nested in another part's hole stays this far from the hole's edge. Blank is 0.
edge_spacing	The strip kept clear along all four edges of every sheet, for clamps or a rough mill edge. Blank is 0.
target	fewest (fewest sheets), waste or cost.
strict	true fails the job when a part cannot be placed.
sheets[]	The sheet sizes to nest on: width, height, quantity (blank for as many as needed), optional material, price and defects, a string of "x y width height" groups split by semicolons, like "100 200 50 30; 900 40 20 20". A row with no width and no height is blank and is dropped. Defects need the Shop plan.
library	An object keyed by part id, each with a quantity and how the part may turn (rotation: fixed, quarter, eighth or any), mirror and rush. Drawings are uploaded and saved in the portal's part library; the API nests what is saved, by the part's id. The part library shows each part's id under its label, with a button to copy it, and GET /v1/parts lists them. A part whose quantity is blank or 0 is left out.
typed[]	Rectangles and circles typed by size: kind, width and height or diameter, quantity, label, rotation, mirror, rush. A row with no size is blank and is dropped.
remnants[]	Ids of the workspace's nest remnants, sheets saved from an earlier nest with the parts already cut, to nest on after the typed sheets. An id sent twice is used once. Remnants need the Shop plan.
deep	true asks for the deep lane once the month's pool is spent. Works plan only.

The exact shapes of each row are in the API reference under NestRequest.

Parts inside holes

Smaller parts nest inside the holes of bigger parts when they fit, on every nest, so a frame or a ring wastes nothing in the middle. A part in a hole keeps part_spacing from the hole's edge. In the DXF export, a part inside a hole comes before the hole around it, and each part's holes before its outline, the order a cutter takes them.

Drawings with gaps and loose ends

Drawings are read in the portal's part library, which repairs what CAD exports often leave behind and says what it did: ends that nearly meet are joined, zero-length segments and segments drawn twice are removed, and small gaps in nearly closed outlines are closed. An outline with a bigger gap stays open and is listed with where its loose ends are, so it can be fixed in the drawing. When the file names no unit and the parts look 25.4 times too small, or the sizes don't fit the unit the file names, the preview says so and offers to read the file again in the likely unit.

Find saved parts

GET /v1/parts lists the workspace's part library, newest first. It is a free call; give unit to have sizes in it, or leave it out for the unit picked on the web.

curl "https://api.nestsolver.com/v1/parts?unit=mm" -H "Authorization: Bearer $NESTSOLVER_KEY"

{
  "unit": "mm",
  "parts": [
    {
      "id": "0192e3b1-4c5d-7e6f-9a0b-1c2d3e4f5a6b",
      "label": "Gusset",
      "width": 240,
      "height": 180.5,
      "holes": 2,
      "rotation": "quarter",
      "mirror": false
    }
  ]
}

width and height are the box around the part. rotation and mirror are how the part was saved to turn and flip; a library row that leaves them out turns by quarter turns and doesn't flip, so send them to keep the saved ones. On MCP this is the list_parts tool.

Limits and refusals

A nest past its tier's part count is refused with 422, the problem's upgrade naming the plan that takes it. Remnants or sheet defects below the Shop plan, and the deep lane below the Works plan, are refused with 403. Plans and limits has the counts.

The answer

202 with the job:

{
  "id": "0192f0c4-7d1e-7c3a-9b2e-5d6f7a8b9c0d",
  "kind": "nest",
  "status": "queued",
  "links": { "status": "https://api.nestsolver.com/v1/jobs/0192f0c4-7d1e-7c3a-9b2e-5d6f7a8b9c0d" }
}

Poll links.status, a full URL. When status is done, the job carries a plan_id and a links.plan URL to read. Jobs and plans has the states.

The plan

A finished nest's report has its sheets[], each with its sheet_row, size and material and the parts placed on it: part_row, label, position, angle, whether it was mirrored, and its outline and holes; metrics for the job, utilization included; unplaced[], each with its part_row; cost_cents; and an explanation. Exports: DXF of the whole nest, SVG of one sheet, part labels and the shop packet. Exports has the formats.

Row numbers

sheet_row and part_row count from 0 over the rows the job kept, not over the request body, so map them back with care:

• Blank rows are dropped before counting: a sheets[] row with no width and no height, a typed[] row with no size, and a library part whose quantity is blank or 0.
• sheet_row counts the kept sheets[] rows in request order, then the remnants[] in request order with repeats dropped.
• part_row counts the saved parts first, in the order of the workspace's part library (not the order of the library object), then the kept typed[] rows in request order.

With no blank rows, sheet_row is the row's place in sheets[], and a typed part's part_row is its place in typed[] plus the number of saved parts asked for. Match a saved part by its label.

What nesting is not

It is not CAM software. The plan says where each part sits; it writes no toolpaths and sets no feeds. Export the DXF and load it into your CAM.