API Reference

Add intelligent container
planning to your platform.

One REST call returns the cheapest container mix, a full packing plan with 3D coordinates, cost analysis, and a shareable viewer link. Integrate in a day.

API operational

Base URLhttps://api.feuteuristix.com

Versionv1

Authx-api-key header

Get your API key →

Quick Start

Make your first simulation call in three steps.

Create a free account at feuteuristix.com. Head to Console → API Keys, create a new key, and copy it. Takes under 2 minutes.

POST your cargo payload

Send your items and container specs to api.feuteuristix.com/simulations with your Bearer token. The engine runs in milliseconds.

Parse the result

The response gives you packedContainers with stats, per-item 3D coordinates, cost analysis, and a simulation ID for the shareable viewer.

Minimal request shape

http

POST https://api.feuteuristix.com/simulations
x-api-key: ftx_live_••••••••••••••••••••••••
Content-Type: application/json

{
  "handlingType": "hand_stuffed",
  "measurementUnits": { "distance": "meter", "weight": "kilogram", "currency": "usd", "utilisation": "percent" },
  "items":      { "Carton-A": { ... } },
  "containers": { "20ft Standard": { ... } }
}

Authentication

All requests require a Bearer token in the Authorization header.

http

x-api-key: ftx_live_<your_api_key>

lock

Hashed storage

Only a SHA-256 hash is stored. Lose a key; revoke it and create a new one.

visibility_off

View once

Shown exactly once at creation. Store it in your secrets manager immediately.

warning

Never expose

Never commit to source control or expose in client-side code.

delete

Revoke anytime

Console → API Keys → Revoke. Takes effect instantly.

Rate Limits

Applied per API key. Exceeding returns 429 Too Many Requests.

Plan	Simulations / month	Requests / min	Max items	Max containers
Free	10	10	20	5
Growth	1,000	60	50	10
Enterprise	Unlimited	300	∞	∞

Need higher limits? Talk to us about enterprise.

API Reference

POST/simulations

Runs the packing engine. Returns the cheapest container combination, full packing plan with per-item 3D coordinates, utilisation stats, and a simulation ID for the shareable 3D viewer.

Request Headers

x-api-keyrequiredftx_live_<your_api_key>

Content-Typerequiredapplication/json

Request Body

chevron_rightmeasurementUnits

objectrequired

Unit system applied to the entire request. All four sub-fields are required.

4 child fields — click to expand

handlingType

stringrequired

"hand_stuffed" | "palletized"

Packing mode. hand_stuffed places items directly into containers. palletized first loads items onto pallets, then pallets into containers. Determines whether the pallets field is required or forbidden.

chevron_rightitems

objectrequired

min 1 key

Map of item type IDs (any string) to item objects. Keys are arbitrary labels for each cargo type (e.g. "Carton-A", "Drum-B").

9 child fields — click to expand

chevron_rightcontainers

objectrequired

min 1 key

Map of container type IDs to container specifications. Define any dimensions — standard ISO types or fully custom sizes.

6 child fields — click to expand

chevron_rightpallets

objectconditional

min 1 key

Map of pallet type IDs to pallet objects.

Required when handlingType is "palletized". Must be omitted for "hand_stuffed".

7 child fields — click to expand

chevron_rightstrategies

objectoptional

Named packing strategies to evaluate side-by-side. If omitted, one "default" strategy runs using all containers for both FCL and SPL. Define multiple strategies to compare cost trade-offs — e.g. "20ft-only" vs "40ft-preferred".

1 child field — click to expand

Example Request

request.json

json

{
  "measurementUnits": {
    "distance": "meter",
    "weight": "kilogram",
    "currency": "usd",
    "utilisation": "percent"
  },
  "handlingType": "hand_stuffed",
  "items": {
    "Carton-A": {
      "length": 0.5,
      "width": 0.4,
      "height": 0.3,
      "weight": 12,
      "quantity": 200,
      "sameStackingOnly": false,
      "maxStackingLevel": 4,
      "possibleOrientations": [
        {
          "length": "length",
          "width": "width",
          "height": "height"
        },
        {
          "length": "width",
          "width": "length",
          "height": "height"
        }
      ]
    },
    "Drum-B": {
      "length": 0.6,
      "width": 0.6,
      "height": 0.9,
      "weight": 80,
      "quantity": 20,
      "sameStackingOnly": true,
      "maxStackingLevel": 1,
      "possibleOrientations": [
        {
          "length": "length",
          "width": "width",
          "height": "height"
        }
      ]
    }
  },
  "containers": {
    "20ft Standard": {
      "length": 5.9,
      "width": 2.35,
      "height": 2.39,
      "weight": {
        "value": 21800,
        "maxUtilisation": 95
      },
      "maxVolumeUtilisation": 90,
      "cost": 1800
    },
    "40ft HC": {
      "length": 12.03,
      "width": 2.35,
      "height": 2.69,
      "weight": {
        "value": 26460,
        "maxUtilisation": 95
      },
      "maxVolumeUtilisation": 90,
      "cost": 2900
    }
  },
  "strategies": {
    "default": {
      "FCL": [
        "20ft Standard",
        "40ft HC"
      ],
      "SPL": [
        "20ft Standard",
        "40ft HC"
      ]
    },
    "40ft-only": {
      "FCL": [
        "40ft HC"
      ],
      "SPL": [
        "40ft HC"
      ]
    }
  }
}

Response Schema — 201 Created

success

boolean

true on success, false on error.

chevron_rightdata

object

Present on success.

3 child fields — click to expand

Example Response

response.json

json

{
  "success": true,
  "data": {
    "id": "a3f72b1c-4d5e-4f6a-b7c8-d9e0f1a2b3c4",
    "entities": {
      "items": {
        "Carton-A": {
          "length": 0.5,
          "width": 0.4,
          "height": 0.3,
          "weight": 12,
          "quantity": 200,
          "color": "#1E90FF"
        },
        "Drum-B": {
          "length": 0.6,
          "width": 0.6,
          "height": 0.9,
          "weight": 80,
          "quantity": 20,
          "color": "#FF6347"
        }
      },
      "containers": {
        "20ft Standard": {
          "length": 5.9,
          "width": 2.35,
          "height": 2.39,
          "volume": {
            "value": 33.14,
            "maxUtilisation": 90
          },
          "weight": {
            "value": 21800,
            "maxUtilisation": 95
          },
          "cost": 1800
        },
        "40ft HC": {
          "length": 12.03,
          "width": 2.35,
          "height": 2.69,
          "volume": {
            "value": 76.06,
            "maxUtilisation": 90
          },
          "weight": {
            "value": 26460,
            "maxUtilisation": 95
          },
          "cost": 2900
        }
      },
      "handlingType": "hand_stuffed",
      "measurementUnits": {
        "distance": "meter",
        "weight": "kilogram",
        "currency": "usd",
        "utilisation": "percent"
      }
    },
    "strategies": {
      "default": {
        "analysis": {
          "cost": {
            "totalCost": 7600,
            "containerQuantity": 3,
            "containers": [
              {
                "container": "40ft HC",
                "quantity": 2,
                "totalCost": 5800
              },
              {
                "container": "20ft Standard",
                "quantity": 1,
                "totalCost": 1800
              }
            ]
          }
        },
        "packedContainers": [
          {
            "id": "40ft HC",
            "packingType": "FCL",
            "quantity": 2,
            "totalCost": 5800,
            "stats": {
              "itemCount": 168,
              "weight": {
                "value": 1952,
                "utilisation": 7.38
              },
              "volume": {
                "value": 9.72,
                "utilisation": 12.78,
                "realisedUtilisation": 100
              },
              "itemDetails": [
                {
                  "id": "Carton-A",
                  "quantity": 168
                }
              ]
            },
            "stacks": [
              [
                {
                  "item": "Carton-A",
                  "quantity": 4,
                  "orientation": {
                    "length": "length",
                    "width": "width",
                    "height": "height"
                  },
                  "coordinates": [
                    0,
                    0,
                    0
                  ]
                }
              ],
              [
                {
                  "item": "Carton-A",
                  "quantity": 4,
                  "orientation": {
                    "length": "length",
                    "width": "width",
                    "height": "height"
                  },
                  "coordinates": [
                    0.5,
                    0,
                    0
                  ]
                }
              ]
            ]
          },
          {
            "id": "20ft Standard",
            "packingType": "SPL",
            "quantity": 1,
            "totalCost": 1800,
            "stats": {
              "itemCount": 52,
              "weight": {
                "value": 2024,
                "utilisation": 9.28
              },
              "volume": {
                "value": 3.85,
                "utilisation": 11.62,
                "realisedUtilisation": 100
              },
              "itemDetails": [
                {
                  "id": "Carton-A",
                  "quantity": 32
                },
                {
                  "id": "Drum-B",
                  "quantity": 20
                }
              ]
            },
            "stacks": [
              [
                {
                  "item": "Carton-A",
                  "quantity": 4,
                  "orientation": {
                    "length": "length",
                    "width": "width",
                    "height": "height"
                  },
                  "coordinates": [
                    0,
                    0,
                    0
                  ]
                }
              ],
              [
                {
                  "item": "Drum-B",
                  "quantity": 1,
                  "orientation": {
                    "length": "length",
                    "width": "width",
                    "height": "height"
                  },
                  "coordinates": [
                    0,
                    0.9,
                    0
                  ]
                }
              ]
            ]
          }
        ]
      }
    }
  }
}

link

Shareable 3D viewer — no UI work required

Every response contains an id. Append it to the console URL for a full interactive 3D packing view — shareable with anyone on your team.

https://feuteuristix.com/console?id=a3f72b1c-4d5e-4f6a-b7c8-d9e0f1a2b3c4

GET/simulations/:id

Fetches a previously created simulation. Returns the full result — entities, strategies, packing plan, 3D coordinates — identical to the POST response structure.

Path Parameters

:id

stringrequired

UUID returned in the id field of the POST /simulations response.

Request Headers

x-api-keyrequiredftx_live_<your_api_key>

Example Request

http

GET https://api.feuteuristix.com/simulations/a3f72b1c-4d5e-4f6a-b7c8-d9e0f1a2b3c4
x-api-key: ftx_live_••••••••••••••••••••••••

Example Response — 200 OK

response.json

json

{
  "success": true,
  "data": {
    "id": "a3f72b1c-4d5e-4f6a-b7c8-d9e0f1a2b3c4",
    "entities": {
      "...": "same as POST response entities"
    },
    "strategies": {
      "...": "same as POST response strategies"
    }
  }
}

Error Reference

All errors use the shape { "success": false, "message": "..." }.

Status	Meaning	Common causes
400	Bad Request	Missing fields, invalid types, dimension conflicts, item doesn't fit in container or pallet.
401	Unauthorized	Missing or invalid Authorization header, expired token.
404	Not Found	No simulation exists for the given :id (GET endpoint).
429	Too Many Requests	Rate limit exceeded. See X-RateLimit-Reset header for when it resets.
500	Internal Server Error	Engine error. Retry with exponential back-off; contact support if it persists.

400Validation error

json

{
  "success": false,
  "message": "\"measurementUnits.distance\" is required"
}

404Not found

json

{
  "success": false,
  "message": "No such resource found, please check the id"
}

500Server error

json

{
  "success": false,
  "message": "Internal server error"
}

Ready to integrate?

Free tier — 10 simulations/month. Enterprise and white-label API pricing for logistics platforms.

Get API key — free Enterprise pricing

Add intelligent containerplanning to your platform.

Quick Start

Authentication

Rate Limits

Error Reference

Add intelligent container
planning to your platform.