ContainerMath

npx add-mcp 'https://mcp.containermath.com'

Quickstart

Send your key as a Bearer token (or the X-API-Key header) and POST a manifest. Call GET /api/v1/containers to list available container/box types.

curl -X POST http://127.0.0.1:4321/api/v1/loadplans/calculate \
  -H "Authorization: Bearer cm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "containerTypeId": "40ft-standard",
    "packingMode": "nested",
    "items": [{
      "id": "sku-1", "name": "Carton A", "itemType": "box",
      "lengthMm": 600, "widthMm": 400, "heightMm": 300,
      "weightKg": 12, "quantity": 200,
      "stackable": true, "fragile": false, "keepUpright": false
    }]
  }'

Responses are JSON: per-container placements, space/weight utilization, axle loads, warnings and loading advice. Requests are metered against your monthly quota; over-quota requests return HTTP 429.

Authentication

Every request needs an API key, created from Developers · API inside your account. The full key is shown once, so store it securely.

Send it as a bearer token:

Authorization: Bearer cm_live_...

…or via the dedicated header:

X-API-Key: cm_live_...

Base URL: http://127.0.0.1:4321/api/v1

The API is available to company accounts on the Pro Plus and Custom plans. Accounts registered on a personal or free-mail address can't create or use API keys and receive 403 company_account_required.

POST /api/v1/loadplans/calculate

Compute a load plan for a cargo manifest. Stateless — nothing is saved.

GET /api/v1/containers

List container/box types you can pack into (built-ins + your custom types).

List the containers you can pack into:

curl http://127.0.0.1:4321/api/v1/containers \
  -H "Authorization: Bearer cm_live_..."

Request body — calculate

Top-level fields for POST /loadplans/calculate.

Field	Type	Notes
containerTypeId	string	A built-in or saved custom container id. Optional if `container` is supplied.
container	object	Inline container/box geometry — an alternative to `containerTypeId` for ad-hoc boxes.
items	array	Cargo items: 1 or more line items (up to 1,000); any total quantity.
packingMode	string	nested (default) · flat · crated · palletized · trolley · mixed.
crateSpec / palletSpec / trolleySpec	object	Optional sub-unit geometry (with matching `*SpecId`) for those modes.
complianceReplan	boolean	Off by default. When the plan breaks a legal axle limit, search for an arrangement of the same cargo in the same vehicle type that clears every limit, and return it in a `compliance` block alongside the plan.
applyComplianceFix	boolean	Off by default. Return the compliant arrangement in place of the plan (implies `complianceReplan`). Runs before every post-pack analysis, so the advice, floor-load, securing and VGM blocks all describe the plan you receive.

Each item

Field	Type	Notes
id, name	string	Your identifier + label for the line item.
itemType	enum	box · cylinder · irregular.
lengthMm, widthMm, heightMm	number	Dimensions in millimetres.
weightKg	number	Per-unit weight.
quantity	integer	Units of this item. Any positive amount — a plan outputs at most 2,000 containers; the rest is reported unplaced.
stackable, fragile, keepUpright	boolean	Handling constraints honoured by the packer.
diameterMm, nestable, packaging, destinationStop	optional	Cylinder bore, telescopic nesting, per-item packaging, multi-stop order.
priority	optional	Load priority (integer 1-99, lower loads first). Overrides default weight/volume ordering; subordinate to destinationStop.
consignmentId	optional string	Shipment reference (PO/AWB/customer ref). Items sharing the same value are always placed in the same container — never split; a group too big for one container is reported unplaced instead.

Response

JSON, identical to what the app's calculator renders.

Field	Description
containersNeeded	Containers in the returned plan (capped at 2,000; the rest spills to unplacedItems).
containerLimitExceeded	true when the load needed more than 2,000 containers, so the plan is truncated and the remainder is unplaced.
spaceUtilizationPercent / weightUtilizationPercent	Cube and payload fill of the first container.
containers[] / placedItems[] / unplacedItems[]	Per-container layout, every placed item's position, and anything that didn't fit.
placedItems[].loadSequence	The order a crew loads each container in, from 1: wall end first, never before what a piece rests on, never after a piece that would block it from the door. Multi-stop loads put the latest stop first wherever that holds. Sort by it for loading steps. Changed in October 2026: it used to be the order the engine placed pieces while searching, which was not always loadable.
weightDistribution / axleLoads	Fore/aft balance and per-axle legal-limit checks (road rigs).
compliance	Present only when you set `complianceReplan`. Axle-compliance verdict (compliant · fixable · unfixable) plus, when a legal arrangement exists, the alternative plan with before/after worst-axle figures and `extraContainers` — the number of extra vehicles the fix costs, which is 0 when compliance is free. Road vessels only.
warnings[]	Imbalance, overweight, door-height and similar advisories.
aiNotes / loadingInstructions[]	Plain-language summary + step-by-step loading guidance.
crates / pallets / trolleys	Sub-unit breakdown for the crated/palletized/trolley/mixed modes.

What the API doesn’t do

Worth knowing before you scope an integration.

No documents. A calculation returns placedItems and each container’s contents — the data to build a packing list. It does not return a packing list, commercial invoice or PDF; those are generated in the Export Documents workspace in the app. Your system renders its own paperwork from the figures.

No equipment optimizer. The API packs into a container you name. Comparing vessel types on cost or volume is an in-app tool.

One stow option is app-only. Overhang pipe nesting isn’t accepted here: it produces an assembly that physically protrudes past its host pipe, so it needs a person to confirm the stow at planning time rather than a background call. Timber dunnage decks are ordinary packing material and are available, as pipeDunnageDecks.

Everything else the engine can do — pack effort, securing, centre-of-gravity envelope, axle groups, floor load, reefer, hazmat, VGM, dunnage estimate, dunnage decks, segregation — is available here as an opt-in flag.

Errors & limits

Errors are JSON: { "error", "message" }.

Status	Error	Meaning
400	validation_error	Malformed body or failed validation.
400	invalid_container	`containerTypeId` not found.
401	invalid_api_key	Missing, malformed, unknown or revoked key.
403	api_access_required	Your plan doesn't include API access.
403	company_account_required	The account is registered on a personal or free-mail address.
403	capability_required	Your plan lacks the capability for this box type.
429	quota_exceeded	Monthly request quota reached.
429	rate_limit_exceeded	Short-term burst limit — back off and retry.

Monthly request quota by plan

Plan	Requests / month
Pro Plus	2,000
Custom	Unlimited

Counted across all your keys, reset on the 1st. A short-term per-minute burst limit also applies. Successful responses include an X-RateLimit-Quota-Remaining header.

Webhooks (ERP / TMS)

Push completed plans into your own systems instead of polling for them.

An organization can register one outbound webhook URL. ContainerMath POSTs a signed JSON payload to it when a load plan is calculated, so an ERP, TMS or WMS can pick the result up without asking for it. Each delivery carries a signature header you verify with the endpoint's shared secret, so you can reject anything that didn't come from us.

Configure it under Organization → Webhooks once you're signed in. Available on Pro Plus and Custom, and only an owner or admin can change it.

Use in Claude & ChatGPT (MCP)

Call ContainerMath from AI assistants over the Model Context Protocol — the same engine as this API. Endpoint: https://mcp.containermath.com.

calculate_cbm no key

Total CBM/CFT, weight, and how cargo fills a 20ft/40ft/40ft HC container. Pure volume math — same as the free CBM calculator, no signup.

plan_cargo_load no key

One cargo size into a container, truck or wagon: units per floor layer and per load, stacking, whether space or payload binds, and how many loads the quantity needs, with a link to the plan on the free Cargo Load Planner.

how_many_pallets_fit no key

How many Euro, standard or US GMA pallets fit a container, trailer, wagon or ULD — the solved floor count, plus the payload limit that often binds first.

get_container_dimensions no key

Interior dimensions, volume, floor area and max payload for 47 containers, trailers, rail wagons and air ULDs.

calculate_load_plan API key

The full 3D load plan — placement, weight & axle, utilisation. Needs a plan with API access.

list_container_types API key

The container/box types you can pack into (built-ins + your custom types).

Add it to Claude Code (the keyed tools use your API key; the free volume, pallet-fit and dimensions tools need no header):

claude mcp add --transport http containermath https://mcp.containermath.com \
  --header "Authorization: Bearer cm_live_..."

In claude.ai, Claude Desktop or ChatGPT, add it as a custom connector pointing at the endpoint above. The three no-key tools work for anyone, on any plan; the packing tools need a plan with API access (same as this REST API).

Building an embedded calculator for your own site instead? The embed widget uses domain-scoped publishable keys and needs no backend.