Developer API

Container loading REST API

Run ContainerMath's load-planning engine from your own systems — SAP, NetSuite, a TMS, a CRM or an internal tool. Authenticate with an API key, POST a cargo manifest, and get back a full load plan: per-container placements, space and weight utilization, axle loads, warnings and loading instructions. It's the same packing engine the web app uses, so API results never drift from the UI.

API access is included on Pro Plus and Custom. Creating and revoking keys happens in your account under Developers · API.

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.

Endpoints

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.
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_cbmno 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.

how_many_pallets_fitno 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_dimensionsno key

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

calculate_load_planAPI key

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

list_container_typesAPI 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.