Start a load

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 LoadRequest 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
stages	string	One stage of spaces, or cartons into pallets into vehicles. "three" needs the Works plan; asked for on another plan, the job is refused with a 403. Anything but "three" reads as "one". One of one , three
mode	string	A one-stage load's placing: stacked in layers, or free. Anything but "free" reads as "stacked". One of stacked , free
target	string	What the plan aims for: the fewest spaces, or the lowest cost. "cost" needs the Works plan; asked for on another plan, the job is refused with a 403. Anything but "cost" reads as "fewest". One of fewest , cost
strict	boolean	Fail when an item 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.
spaces	array of LoadSpace	A one-stage load's spaces. At most 30 rows.
cartons	array of LoadSpace	Three stages: the cartons items go into. At most 30 rows.
pallets	array of LoadSpace	Three stages: the pallets cartons go onto. At most 30 rows.
vehicles	array of LoadSpace	Three stages: the vehicles pallets go into. At most 30 rows.
cargo	array of LoadCargo	The items to load. At most 200 rows.

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, or a Free workspace started its 5 loads this month; `upgrade` names the plan that takes it.	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 loads 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/loads \
  -H "Authorization: Bearer $NESTSOLVER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "unit": "mm",
  "spaces": [
    {
      "kind": "pallet",
      "label": "EUR pallet",
      "length": "1200",
      "width": "800",
      "height": "1800",
      "own_weight": "25",
      "weight_limit": "1000",
      "quantity": "",
      "price": "38.50",
      "loading": "back"
    }
  ],
  "cargo": [
    {
      "label": "Box",
      "length": "400",
      "width": "300",
      "height": "250",
      "weight": "12",
      "quantity": "24",
      "turning": "upright"
    }
  ]
}'

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

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