Reference

Every request and response field of the API, the error responses and the limits. The components' API is in Embedding the components and in cartonization-components.d.ts.

Conventions#

• Units. Any consistent unit: use one length unit for every dimension (for example cm) and one weight unit for every weight (for example kg). The service never converts. Dimensions must be between 0.01 and 1,000,000; if your values are smaller, use a smaller unit (for example mm).
• Coordinates. x runs along the container's length, y along its width, z is up (height). The origin is the inner corner of the container's floor. A placement's length, width and height are the unit's dimensions in its chosen orientation.
• Ids. 1 to 100 characters, trimmed, unique within the request (per list), and they may not contain #. Each unit of an item is named <id>#<n> (n from 1), or just <id> when the item's quantity is 1.
• Optional fields can be left out. null is not accepted where a value is expected.

POST /api/pack#

Packs items into containers with one, several or all algorithms, and returns the best solution and the ranking.

{
  "containers": [{ "id": "M", "length": 35, "width": 25, "height": 20, "maxWeight": 20, "quantity": 10, "cost": 0.8 }],
  "items": [{ "id": "SKU1", "length": 12, "width": 9, "height": 10, "weight": 0.4, "quantity": 4, "rotation": "upright", "stackable": true }],
  "options": { "minSupportRatio": 0.7, "timeLimitMs": 2000, "totalTimeLimitMs": 15000, "objective": "fill-rate", "heavyOnBottom": false, "seed": 42 },
  "algorithm": "best",
  "includeAllSolutions": false
}

Container#

A box type, pallet type or bin location.

Item#

Options#

Algorithms#

GET /api/algorithms lists them with their names and descriptions.

Every algorithm uses the same container selection: several box types, quantity limits, and right-sizing each container down to the smallest box that still holds its contents.

Ranking and objectives#

The fewest unpacked units always come first: a solution that leaves items behind never wins. Then options.objective decides:

With the default, fill rate comes before the container count, so the winner can occasionally use one more, smaller box than another algorithm. The response reports the objective that was used. Under lowest-cost a container without cost counts as free, so give every container type a cost when you use it.

Constraints#

• Hazmat. An item with hazmatClass only goes into a container with hazmat: true, and hazmat containers hold only hazmat items, one hazard class per container. hazmatClasses limits the classes a hazmat container is certified for; leave it out to accept any class. A hazmat item with no certified container is returned in unpacked. Packed hazmat containers report their hazmatClass. Classes match regardless of case and spacing ("class 8" = "Class 8") and are reported in upper case. When hazmat groups share quantity-limited containers, the group with the fewest certified container types is packed first.
• Heavy on bottom (options.heavyOnBottom). No item may rest on a lighter item.
• Crush limit (item.maxLoad). The load is passed down through stacks and split by contact area.
• Overhang (container.maxOverhang). Placements can then have negative x / y (relative to the nominal corner), and the container's fill rate is measured against the overhang envelope, (length + 2·o) × (width + 2·o) × height.
• Support. Every item above the floor rests on something; minSupportRatio sets how much of its base. A stackable: false item has nothing on top of it.

Response#

{ "best": { ... }, "ranking": [ ... ], "objective": "fill-rate", "skipped": [], "solutions": [ ... ] }

Solution#

PackedContainer#

Placement#

SolutionMetrics#

RankingEntry#

{ rank, algorithm, metrics, elapsedMs }: rank from 1, metrics as in SolutionMetrics. The ranking has no placements; send includeAllSolutions: true to get every solution.

Unpacked reasons#

POST /api/capacity#

How many of one item fit in one container, and how many containers N units need. For example, how many cartons fit on a pallet:

{ "container": { "id": "EUR", "length": 120, "width": 80, "height": 160, "maxWeight": 800 },
  "item": { "id": "CTN", "length": 40, "width": 30, "height": 30, "weight": 9, "rotation": "upright" },
  "demand": 1000 }

The response:

POST /api/pack/multi-level#

Packs through 1 to 3 nested levels in one request, for example items into cartons, then cartons onto pallets:

{
  "items": [
    { "id": "MUG", "length": 12, "width": 9, "height": 10, "weight": 0.4, "quantity": 30, "rotation": "upright" },
    { "id": "PAINT", "length": 10, "width": 10, "height": 12, "weight": 1.2, "quantity": 6, "hazmatClass": "3" }
  ],
  "levels": [
    { "name": "Cartons", "algorithm": "best", "options": { "timeLimitMs": 500 },
      "containers": [
        { "id": "BOX-M", "length": 30, "width": 25, "height": 20, "maxWeight": 20, "tareWeight": 0.3, "outerLength": 31, "outerWidth": 26, "outerHeight": 21 },
        { "id": "HZ-BOX", "length": 30, "width": 20, "height": 20, "hazmat": true, "hazmatClasses": ["3"] } ] },
    { "name": "Pallets", "options": { "minSupportRatio": 0.7, "heavyOnBottom": true },
      "containers": [
        { "id": "EURO", "length": 120, "width": 80, "height": 150, "maxWeight": 1000, "tareWeight": 25, "maxOverhang": 2 },
        { "id": "HZ-PALLET", "length": 120, "width": 80, "height": 150, "hazmat": true } ] }
  ]
}

• items are packed at level 1. Each level has its own containers (1 to 100), options, algorithm (unknown algorithms on any level return 400) and an optional name (1 to 50 characters).
• Every container packed at level k becomes one item of level k+1, with id <containerId>@<index>: footprint outerLength / outerWidth (default: the inner size + 2 × maxOverhang), height outerHeight (default: the inner height). For pallets, set baseHeight (the deck height): the loaded pallet is then baseHeight + its actual load height tall at the next level, not its virtual height. The other fields carried over are the weight (the container's gross weight: contents + tareWeight), rotation (default upright), stackable (default true), maxLoad and the container's hazmatClass. So a hazmat carton needs a hazmat pallet certified for its class.
• The response is { levels: [{ name, best, ranking, objective, skipped }], summary: [{ name, containerCount, fillRate, unpackedUnits }] }. On a trial license the response and every level also have license: { trial: true }, so a level passed to the components on its own still shows the TRIAL mark. Units left unpacked at a level stay in that level's unpacked; if a level packs nothing, the later levels return an empty solution.

GET /api/algorithms and GET /health#

• GET /api/algorithms: [{ id, name, description, kind }], where kind is constructive or metaheuristic.
• GET /health: {"status":"ok"}, whatever the license says.

GET /v1/info#

The version and the license of this install, the same for every caller (it never contains the key, nor why a key was rejected: that is only in the server log). The Status page shows it. Never blocked, also without a license.

{"name":"cartonization","version":"1.0.0","license":{"status":"valid","trial":false,"source":"configured","allowed":{"cartonization":true},"products":["cartonization"],"licensee":"Acme Corp","id":"LIC-0007","expires":"2027-10-31","daysLeft":375,"maxInstances":2,"instanceId":"cz-3f9a51c0d2e47b8a16c5e0f1"}}

Fields that don't apply are absent.

Errors#

Each entry of issues has path (the field, as a list of keys and indexes, for example ["containers", 0, "length"]), message and code, plus details that depend on the code (for example minimum):

{"error":"Invalid request","issues":[{"origin":"number","code":"too_small","minimum":0.01,"inclusive":true,"path":["containers",0,"length"],"message":"dimensions must be at least 0.01 (use a smaller unit, e.g. mm)"}]}

• A 503 because the solver is busy carries Retry-After: 1; a 503 because a request exceeded SOLVER_TIMEOUT_MS has no Retry-After (retrying the same request won't help). The clients honor the header.
• Units left out of a packing are not an error: the response is 200, and best.unpacked lists each unit with its reason.

Limits#

• At most 2000 units per request (the sum of the item quantities; for multi-level, the level-1 items), at most 100 container types (per level), and container types × units at most 50,000 (per level, counting the level-1 units). The last cap bounds the work: the service tries every container type for every container it opens.
• Dimensions between 0.01 and 1e6 in any consistent unit; ids may not contain #. Hazard classes are 1 to 20 characters; maxLoad, maxOverhang and baseHeight are at least 0; outer dimensions follow the same 0.01 to 1e6 rule and must be at least the inner dimensions. Request bodies up to 5 MB.
• Container types: any number of box sizes, pallet types or bin locations, each with an optional quantity.
• Time: timeLimitMs (10 to 10000, default 2000) bounds each metaheuristic, which also stops early once it stops improving. totalTimeLimitMs (100 to 60000, default 15000) is the budget for a whole multi-algorithm run: the constructive algorithms run first, and the metaheuristics share what is left (each gets at most timeLimitMs). Once it is used up, the remaining algorithms are skipped (listed in skipped), but at least one always runs. For multi-level requests it applies per level. A metaheuristic always finishes its first evaluation (one full packing), so on very large instances it can exceed a small timeLimitMs by about one constructive run.
• Server timeouts: every request is solved in a worker thread, so the server stays responsive. A request still solving after SOLVER_TIMEOUT_MS (default 200 s, above 3 levels × the 60 s maximum totalTimeLimitMs) returns 503, and so do requests beyond SOLVER_MAX_CONCURRENT (default: the CPU count) running at the same time.
• Rough timings in "best" mode: typical orders and pallets take under 1 s plus the metaheuristic budget. A 2000-unit pallet takes a few seconds in total.