Start a nest

Headers and parameters

Field	Type	Meaning
Idempotency-Key (header)	string	Send the same key and body to get the first answer again, for a day; nothing new starts.

Request body

A NestRequest as JSON. Required fields are marked; the rest may be left out.

Field	Type	Meaning
unit required	string	The unit lengths are typed in. One of mm , cm , m , in
part_spacing	string	The gap kept between parts, in unit; blank is 0. It holds inside holes too: smaller parts nest in bigger parts' holes and keep this gap from the hole's edge.
edge_spacing	string	The strip kept clear along all four edges of every sheet, in unit, for clamps or a rough edge; blank is 0.
target	string	What the nest aims for: the fewest sheets, the least waste, or the lowest cost. Anything else reads as "fewest". One of fewest , waste , cost
strict	boolean	Fail when a part is left out.
deep	boolean	Once the month's full-speed pool is spent, search in the deep lane rather than the slower one: the plan's whole search time, starting once the workspace has nothing else waiting or running. Within the pool it changes nothing. Needs the Works plan; asked for on another plan, the job is refused with a 403.
sheets	array of NestSheet	Sheet rows. A row with no width and no height is blank and is dropped. At most 200 rows.
library	object of NestLibraryRow	Saved parts by id: the workspace's part library, which GET /v1/parts lists with each part's id. A part whose quantity is blank or 0 is left out. At most 200 parts.
typed	array of NestTypedRow	Rectangles and circles typed by size. A row with no size (no width and no height, or no diameter for a circle) is blank and is dropped. At most 200 rows.
remnants	array of string	Ids of the workspace's nest remnants, sheets saved from an earlier nest, to nest on after the typed sheets. An id sent twice is used once. Needs the Shop plan; asked for on another plan, the job is refused with a 403. At most 200 ids.

Responses

Status	When	Body
202	Queued; watch its status link.	Started
400	An Idempotency-Key that isn't 1 to 255 characters.	Errors
401	No live API key.	Errors
403	The plan doesn't include this; `upgrade` names the plan that does.	Errors
409	A request with this Idempotency-Key is still running.	Errors
413	A body over 4 MB.	Errors
422	The request breaks a rule, each problem naming its field, or its Idempotency-Key was used for another request, or it holds more rows or longer text than the API takes.	Errors
429	More than 30 solves and job starts this minute (6 on Free), the workspace already has 5 nests waiting, or more than 600 calls from this address.	Errors
500	Something went wrong on our side; try again.	Errors

Example

A sample request: the body's required fields, and one row of each kind when the body requires none.

curl -X POST https://api.nestsolver.com/v1/nests \
  -H "Authorization: Bearer $NESTSOLVER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "unit": "mm",
  "sheets": [
    {
      "width": "2440",
      "height": "1220",
      "quantity": "5",
      "price": "38.50",
      "material": ""
    }
  ],
  "library": {
    "0192f0b8-3c2a-7e41-8d5f-1a2b3c4d5e6f": {
      "quantity": "4",
      "rotation": "quarter"
    }
  },
  "typed": [
    {
      "kind": "rectangle",
      "width": "600",
      "height": "400",
      "quantity": "4",
      "label": "Side panel",
      "rotation": "quarter"
    }
  ]
}'

A 202 answer, required fields only; lists show one item:

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