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 Freight Pro, 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

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.

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

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	`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
Freight Pro	1,000
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.

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 calculate_cbm needs 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. Free and Starter plans can use calculate_cbm; 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.