CubeMaster API V2 User's Guide

The CubeMaster API V2, hosted at https://api.cubemaster.net, is a RESTful API designed for building and managing truck, trailer, pallet, ULD, and box loads. It includes:

Calculation API: Build loads remotely.
Database API: Manage cargo and container master data.
Archive API: Access and manage saved loads.
Edit API: Edit load data.
Upload API: Upload Excel files for mass load creation.

Explore the API definitions at /v2/swagger.json. Basic knowledge of RESTful APIs and JSON is assumed.

All requests require an API key. Obtain yours from your CubeMaster account under Settings > Integration. Include it in the header:

TokenID: YOUR_API_KEY

To test endpoints, use the "Authorize" button in the Swagger UI at /v2/swagger.json.

POST /loads

Builds a new load and saves it to the loads database. Overwrites a load with the same title.

Parameters

Name	Type	Description	Default
multiProcessed	boolean (query)	Set true for asynchronous processing with webhook result delivery. False for immediate results.	false
cargoDetailLoadedFromDatabase	boolean (query)	If true, cargo details are loaded from the database by name.	false
containerDetailLoadedFromDatabase	boolean (query)	If true, container details are loaded from the database by name.	false
loadSaved	boolean (query)	If true, the load is saved to the database.	true
loadShared	boolean (query)	If true, the load is shared company-wide.	true
userId	string (query)	Email of the user under whom the load is saved.	API credential email
webhookListenerURLToNewLoad	string (query)	Webhook URL for asynchronous load results.	none
graphicsCreated	boolean (query)	If true, generates container graphics.	false
graphicsImageWidth	integer (query)	Width of graphics in pixels.	200
graphicsImageDepth	integer (query)	Depth of graphics in pixels.	200
graphicsShowScale	boolean (query)	If true, includes measurements in graphics.	false
graphicsBackgroundColorRGB	integer (query)	RGB color for graphics background.	0
thumbnailsCreated	boolean (query)	If true, generates space thumbnails.	false
thumbnailsImageWidth	integer (query)	Width of thumbnails in pixels.	200
thumbnailsImageDepth	integer (query)	Depth of thumbnails in pixels.	200
thumbnailsCreatedInBlackWhite	boolean (query)	If true, thumbnails are in black and white.	false
spacesCreated	boolean (query)	If true, includes space details.	false
placementsCreated	boolean (query)	If true, includes placement details.	false
UOM	string (query)	Unit of measure (UnitEnglish, UnitMetric, UnitHighMetric).	UnitEnglish
reportLanguage	string (query)	Language for reports (ENG, GER, SPN, FRN, BRZ, CHN, JPN, KOR).	ENG
reportToolbarShown	boolean (query)	If true, shows report toolbar.	false

Request Body

{
    "title": "Truck Load 001",
    "description": "Sample truck load",
    "cargoes": [
        {
            "style": "shipcase",
            "name": "Box A",
            "length": 10,
            "width": 5,
            "height": 3,
            "weight": 20,
            "qty": 50
        }
    ],
    "emptyContainers": [
        {
            "containerType": "Truck",
            "name": "Truck 1",
            "length": 20,
            "width": 8,
            "height": 8,
            "maxWeight": 1000
        }
    ],
    "rules": {
        "calculationType": "MixLoad",
        "algorithmType": "Optimization"
    }
}

Response

{
    "status": "succeed",
    "message": "OK",
    "calculationError": null,
    "document": {
        "title": "Truck Load 001",
        "description": "Sample truck load",
        "isShared": true,
        "isAutoSaved": true,
        "calculationTimeInSeconds": 5,
        "processId": "proc_123",
        "createdBy": "user@example.com",
        "createdAt": "2025-03-26T10:00:00Z",
        "updatedAt": "2025-03-26T10:00:05Z",
        "containerType": "Truck",
        "calculationType": "MixLoad"
    },
    "loadSummary": {
        "cargoesLoaded": 50,
        "piecesLoaded": 50,
        "cargoesLeft": 0,
        "piecesLeft": 0,
        "unitloadsLoaded": 1,
        "weightAdded": 1000
    },
    "filledContainers": [
        {
            "name": "Truck 1_1",
            "sequence": 1,
            "loadQty": 50,
            "grossWeight": 1000,
            "volumeUtilization": 80.5
        }
    ]
}

GET /Database/Cargoes/{name}

Retrieves a cargo by name from the cargoes database.

Request

GET /Database/Cargoes/Box%20A

Response

{
    "style": "shipcase",
    "name": "Box A",
    "description": "Standard shipping box",
    "length": 10,
    "width": 5,
    "height": 3,
    "weight": 20
}

DELETE /Database/Cargoes/{name}

Deletes a cargo by name from the cargoes database.

GET /Database/Cargoes

Retrieves all cargoes from the cargoes database.

POST /Database/Cargoes/Multiple

Inserts multiple cargoes into the cargoes database.

Request

{
    "cargoes": [
        {"style": "shipcase", "name": "Box A", "length": 10, "width": 5, "height": 3, "weight": 20},
        {"style": "palletload", "name": "Pallet B", "length": 48, "width": 40, "height": 50, "weight": 500}
    ]
}

PUT /Database/Cargoes/{keyIs}

Updates a cargo (partial updates supported).

GET /Database/Containers/{type}

Retrieves all containers of a specific type.

POST /Database/Containers/{type}

Inserts a container into the containers database.

GET /Database/Containers/{type}/{name}

Retrieves a container by type and name.

DELETE /Database/Containers/{type}/{name}

Deletes a container by type and name.

Note: Full request/response examples for some endpoints are pending detailed documentation.

GET /Loads

Retrieves all saved loads from the database.

Parameters

Name	Type	Description	Default
limit	integer (query)	Limits the number of loads returned.	10
createdAt	string (query)	Filter by creation date.	none
shared	boolean (query)	If true, returns only shared loads.	false
graphicsCreated	boolean (query)	If true, includes graphics.	false
graphicsImageWidth	integer (query)	Width of graphics in pixels.	200
graphicsImageDepth	integer (query)	Depth of graphics in pixels.	200
graphicsShowScale	boolean (query)	If true, includes measurements in graphics.	false
graphicsBackgroundColorRGB	integer (query)	RGB color for graphics background.	0
thumbnailsCreated	boolean (query)	If true, generates space thumbnails.	false
thumbnailsImageWidth	integer (query)	Width of thumbnails in pixels.	200
thumbnailsImageDepth	integer (query)	Depth of thumbnails in pixels.	200
thumbnailsCreatedInBlackWhite	boolean (query)	If true, thumbnails are in black and white.	false
spacesCreated	boolean (query)	If true, includes space details.	false
placementsCreated	boolean (query)	If true, includes placement details.	false
UOM	string (query)	Unit of measure (UnitEnglish, UnitMetric, UnitHighMetric).	UnitEnglish

Response

{
    "status": "succeed",
    "message": "Loads retrieved",
    "document": [
        {
            "title": "Truck Load 001",
            "isShared": true,
            "createdAt": "2025-03-26T10:00:00Z"
        }
    ]
}

GET /Loads/{userId}/{title}

Retrieves a specific load by user ID and title.

DELETE /Loads/{userId}/{title}

Deletes a load by user ID and title.

GET /Loads/{userId}/{title}/{filledContainerSeq}

Retrieves a specific filled container from a load.

Note: Full request/response examples for some endpoints are pending detailed documentation.

POST /Edit/Load/{userId}

Builds a load from editing data and saves it.

GET /Edit/{userId}

Retrieves editing data for a user.

DELETE /Edit/{userId}

Deletes editing data for a user.

GET /Edit/Load/{userId}/{filledContainerSeq}

Retrieves a filled container from editing data.

Note: Full request/response examples are pending detailed documentation.

POST /Upload/Excel

Uploads an Excel file to build mass loads.

Note: Request/response examples and schema details are pending further documentation.

Cargo

Represents cargo details for load calculation. For more details, go here.

{
    "style": "string",
    "name": "string",
    "description": "string",
    "length": "number",
    "width": "number",
    "height": "number",
    "weight": "number",
    "qty": "integer",
    "unitLoadQty": "integer",
    "maxStack": "integer",
    "turnable": "boolean",
    "tiltable": "boolean",
    "bottomOnly": "boolean",
    "group": "string",
    "priority": "integer",
    "allowMix": "boolean",
    "destination": "string",
    "colorRGB": "integer"
}

EmptyContainer

Defines an empty container for load planning. For more details, go here.

{
    "containerType": "string",
    "name": "string",
    "description": "string",
    "length": "number",
    "width": "number",
    "height": "number",
    "maxWeight": "number",
    "maxVolume": "number",
    "tareWeight": "number",
    "cost": "number",
    "colorRGB": "integer"
}

FilledContainer

Represents a container filled with cargo after load calculation. For more details, go here.

{
    "name": "string",
    "sequence": "integer",
    "loadQty": "integer",
    "grossWeight": "number",
    "volumeUtilization": "number",
    "length": "number",
    "width": "number",
    "height": "number",
    "tareWeight": "number",
    "maxWeight": "number",
    "graphics": "string",
    "thumbnails": "string",
    "spaces": ["string"],
    "placements": ["string"]
}

Rules

Specifies calculation rules for load building.

{
    "calculationType": "string",
    "algorithmType": "string",
    "maxUnitLoads": "integer",
    "maxTimeInSeconds": "integer",
    "maxPiles": "integer",
    "maxMixedCargoes": "integer",
    "maxOverhangLength": "number",
    "maxOverhangWidth": "number",
    "allowMix": "boolean",
    "allowStack": "boolean",
    "allowTilt": "boolean",
    "allowTurn": "boolean"
}

Load

Represents a complete load request.

{
    "title": "string",
    "description": "string",
    "cargoes": ["Cargo"],
    "emptyContainers": ["EmptyContainer"],
    "rules": "Rules"
}

Common error responses:

{
    "status": "error",
    "code": 400,
    "message": "Bad Request: Invalid parameters"
}

{
    "status": "error",
    "code": 401,
    "message": "Unauthorized: Invalid API key"
}

Q: How do I get an API key?

A: Log into your CubeMaster account, go to Settings > Integration, and generate or copy your API key. Use it in the header like this:

TokenID: YOUR_API_KEY

Q: What happens if I send a load with an existing title?

A: The existing load will be overwritten. For example:

{
    "title": "Truck Load 001",
    "description": "Updated truck load",
    "cargoes": [{"style": "shipcase", "name": "Box A", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 50}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 1", "length": 20, "width": 8, "height": 8, "maxWeight": 1000}],
    "rules": {"calculationType": "MixLoad", "algorithmType": "Optimization"}
}

Q: Can I test the API without saving loads?

A: Yes, set loadSaved=false. Example:

POST /loads?loadSaved=false
{
    "title": "Test Load",
    "cargoes": [{"style": "shipcase", "name": "Box B", "length": 12, "width": 6, "height": 4, "weight": 25, "qty": 30}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 2", "length": 25, "width": 8, "height": 8, "maxWeight": 1200}]
}

Q: How do asynchronous requests work?

A: Use multiProcessed=true and provide a webhook URL. Example:

POST /loads?multiProcessed=true&webhookListenerURLToNewLoad=https://your-webhook.com
{
    "title": "Async Load",
    "cargoes": [{"style": "palletload", "name": "Pallet C", "length": 48, "width": 40, "height": 50, "weight": 500, "qty": 5}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 3", "length": 30, "width": 8, "height": 8, "maxWeight": 5000}]
}

Q: What units of measure are supported?

A: UnitEnglish, UnitMetric, and UnitHighMetric. Example using metric:

POST /loads?UOM=UnitMetric
{
    "title": "Metric Load",
    "cargoes": [{"style": "shipcase", "name": "Box D", "length": 25.4, "width": 12.7, "height": 7.6, "weight": 9.07, "qty": 40}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 4", "length": 6.1, "width": 2.4, "height": 2.4, "maxWeight": 453.59}]
}

Q: How do I view generated graphics?

A: Set graphicsCreated=true. Example:

POST /loads?graphicsCreated=true&graphicsImageWidth=300&graphicsImageDepth=300
{
    "title": "Graphics Load",
    "cargoes": [{"style": "shipcase", "name": "Box E", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 20}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 5", "length": 15, "width": 8, "height": 8, "maxWeight": 800}]
}

Q: What if I encounter a 401 error?

A: Check your API key. A correct request looks like:

GET /Loads HTTP/1.1
Host: api.cubemaster.net
ToeknID: YOUR_API_KEY

Q: How do I retrieve all saved loads?

A: Use GET /Loads. Example:

GET /Loads?limit=5&shared=true

Q: Can I delete a specific load?

A: Yes, use DELETE /Loads/{userId}/{title}. Example:

DELETE /Loads/user@example.com/Truck%20Load%20001

Q: How do I add cargo to the database?

A: Use POST /Database/Cargoes/Multiple. Example:

{
    "cargoes": [
        {"style": "shipcase", "name": "Box F", "length": 15, "width": 10, "height": 5, "weight": 30}
    ]
}

Q: How do I update a cargo?

A: Use PUT /Database/Cargoes/{keyIs}. Example:

PUT /Database/Cargoes/Box%20F
{
    "weight": 35
}

Q: What’s the difference between synchronous and asynchronous processing?

A: Synchronous (multiProcessed=false) returns results immediately, while asynchronous (multiProcessed=true) uses a webhook for larger loads.

Q: How do I specify a custom background color for graphics?

A: Use graphicsBackgroundColorRGB. Example (red background):

POST /loads?graphicsCreated=true&graphicsBackgroundColorRGB=16711680
{
    "title": "Red Graphics Load",
    "cargoes": [{"style": "shipcase", "name": "Box G", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 10}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 6", "length": 12, "width": 8, "height": 8, "maxWeight": 600}]
}

Q: Can I retrieve a specific container from a load?

A: Yes, use GET /Loads/{userId}/{title}/{filledContainerSeq}. Example:

GET /Loads/user@example.com/Truck%20Load%20001/1

Q: How do I share a load company-wide?

A: Set loadShared=true. Example:

POST /loads?loadShared=true
{
    "title": "Shared Load",
    "cargoes": [{"style": "shipcase", "name": "Box H", "length": 8, "width": 4, "height": 2, "weight": 15, "qty": 25}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 7", "length": 18, "width": 8, "height": 8, "maxWeight": 900}]
}

Q: What languages are supported for reports?

A: ENG, GER, SPN, FRN, BRZ, CHN, JPN, KOR. Example (German):

POST /loads?reportLanguage=GER
{
    "title": "German Report Load",
    "cargoes": [{"style": "shipcase", "name": "Box I", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 15}],
    "emptyContainers": [{"containerType": "Truck", "name": "Truck 8", "length": 20, "width": 8, "height": 8, "maxWeight": 1000}]
}

Q: How do I handle large datasets?

A: Use the POST /Upload/Excel endpoint for mass uploads. (Detailed example pending further documentation.)

Tutorial 1: Creating and Saving a Basic Load

Steps to create a truck load with cargo and save it.

Prepare the Request: Define cargo and container details.

{
    "title": "Basic Truck Load",
    "description": "Tutorial load",
    "cargoes": [
        {
            "style": "shipcase",
            "name": "Tutorial Box",
            "length": 10,
            "width": 5,
            "height": 3,
            "weight": 20,
            "qty": 40
        }
    ],
    "emptyContainers": [
        {
            "containerType": "Truck",
            "name": "Tutorial Truck",
            "length": 20,
            "width": 8,
            "height": 8,
            "maxWeight": 1000
        }
    ],
    "rules": {
        "calculationType": "MixLoad",
        "algorithmType": "Optimization"
    }
}

Send the Request: Use POST /loads with your API key.

POST /loads HTTP/1.1
Host: api.cubemaster.net
TokenID: YOUR_API_KEY
Content-Type: application/json

[Request body from Step 1]

Check the Response: Verify the load was created and saved.

{
    "status": "succeed",
    "message": "OK",
    "document": {
        "title": "Basic Truck Load",
        "isShared": true,
        "createdBy": "user@example.com",
        "createdAt": "2025-03-26T12:00:00Z"
    },
    "loadSummary": {
        "cargoesLoaded": 40,
        "weightAdded": 800
    },
    "filledContainers": [
        {
            "name": "Tutorial Truck_1",
            "sequence": 1,
            "loadQty": 40,
            "grossWeight": 800,
            "volumeUtilization": 75.0
        }
    ]
}

Tutorial 2: Using Database Cargo and Containers

Steps to build a load using pre-saved database entries.

Add Cargo to Database: Save cargo details.

POST /Database/Cargoes/Multiple HTTP/1.1
Host: api.cubemaster.net
TokenID: YOUR_API_KEY
Content-Type: application/json

{
    "cargoes": [
        {"style": "shipcase", "name": "DB Box", "length": 12, "width": 6, "height": 4, "weight": 25}
    ]
}

Add Container to Database: Save container details.


    POST /Database/Containers/Truck HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY
    Content-Type: application/json

    {
    "name": "DB Truck",
    "length": 25,
    "width": 8,
    "height": 8,
    "maxWeight": 1200
    }

Create Load from Database: Use database references.


    POST /loads?cargoDetailLoadedFromDatabase=true&containerDetailLoadedFromDatabase=true HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY
    Content-Type: application/json

    {
    "title": "DB Load",
    "cargoes": [{"name": "DB Box", "qty": 30}],
    "emptyContainers": [{"containerType": "Truck", "name": "DB Truck"}],
    "rules": {"calculationType": "MixLoad"}
    }

Verify Response: Check the load details.

{
    "status": "succeed",
    "message": "OK",
    "filledContainers": [
        {
            "name": "DB Truck_1",
            "sequence": 1,
            "loadQty": 30,
            "grossWeight": 750,
            "volumeUtilization": 60.0
        }
    ]
}

Tutorial 3: Generating Graphics and Reviewing a Load

Steps to create a load with graphics and retrieve it.

Create Load with Graphics: Enable graphics generation.


    POST /loads?graphicsCreated=true&graphicsShowScale=true HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY
    Content-Type: application/json

    {
    "title": "Graphics Load",
    "cargoes": [{"style": "shipcase", "name": "Graphics Box", "length": 10, "width": 5, "height": 3, "weight": 20, "qty": 20}],
    "emptyContainers": [{"containerType": "Truck", "name": "Graphics Truck", "length": 15, "width": 8, "height": 8, "maxWeight": 800}]
    }

Check Graphics in Response: Look for graphics URLs.

{
    "status": "succeed",
    "filledContainers": [
        {
            "name": "Graphics Truck_1",
            "sequence": 1,
            "loadQty": 20,
            "grossWeight": 400,
            "volumeUtilization": 50.0,
            "graphics": "https://api.cubemaster.net/graphics/12345"
        }
    ]
}

Retrieve the Load: Use GET /Loads.


    GET /Loads/user@example.com/Graphics%20Load HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY

Review Specific Container: Access a filled container.


    GET /Loads/user@example.com/Graphics%20Load/1 HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY

Tutorial 4: Asynchronous Load Processing

Steps to process a large load asynchronously.

Set Up Webhook: Ensure your server has a webhook endpoint (e.g., https://your-webhook.com/load-result).
Send Asynchronous Request: Use multiProcessed=true.


    POST /loads?multiProcessed=true&webhookListenerURLToNewLoad=https://your-webhook.com/load-result HTTP/1.1
    Host: api.cubemaster.net
    TokenID: YOUR_API_KEY
    Content-Type: application/json

    {
    "title": "Large Async Load",
    "cargoes": [
    {"style": "palletload", "name": "Large Pallet", "length": 48, "width": 40, "height": 50, "weight": 500, "qty": 10}
    ],
    "emptyContainers": [
    {"containerType": "Truck", "name": "Large Truck", "length": 40, "width": 8, "height": 8, "maxWeight": 6000}
    ]
    }

Receive Webhook Response: Your server will get a POST request with the result.

{
    "status": "succeed",
    "message": "OK",
    "document": {
        "title": "Large Async Load",
        "createdAt": "2025-03-26T14:00:00Z"
    },
    "filledContainers": [
        {
            "name": "Large Truck_1",
            "sequence": 1,
            "loadQty": 10,
            "grossWeight": 5000,
            "volumeUtilization": 85.0
        }
    ]
}