API DOCUMENTATION
packHQ API
Reference
Integrate AI-powered 3D bin packing into your application with a single REST endpoint.
REST API
<200ms
Quickstart — first call in 5 minutes
No account needed for the Sandbox. For the API endpoint, get a key from your dashboard.
curl example
curl -X POST https://app.packhq.cloud/api/pack \
-H "Content-Type: application/json" \
-H "X-Api-Key: YOUR_API_KEY" \
-d '{
"items": [
{ "name": "Shoe Box", "length": 12, "width": 7, "height": 5, "unit": "in", "quantity": 4 }
],
"containers": [
{ "name": "Carton", "length": 24, "width": 16, "height": 12, "unit": "in" }
]
}'Sample 200 response (abbreviated)
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"containers": [
{
"name": "Carton",
"length": 24, "width": 16, "height": 12, "unit": "in",
"items": [
{ "name": "Shoe Box", "x": 0, "y": 0, "z": 0, "dx": 12, "dy": 7, "dz": 5, "nx": 1, "ny": 1, "nz": 1 }
]
}
],
"unpackedItems": []
}POST
/api/packSubmit items and containers for AI-optimized 3D packing. Returns exact placement coordinates for each item.
Request Headers (commercial tier)
| Header | Required | Description |
|---|---|---|
X-Api-Key | Commercial only | API key issued by P4 Software. Required for commercial tier access. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
items | array | Yes | Array of item objects to pack |
containers | array | Yes | Array of available container types |
singleSkuPerContainer | boolean | — | If true, each container holds only one item type |
maxContainerWeight | number | — | Maximum weight per container (uses weightUnit) |
weightUnit | string | — | "lb" or "kg" (default: "lb") |
Item Object
| Field | Type | Description |
|---|---|---|
name | string | Descriptive label for the item |
length | number | Length dimension |
width | number | Width dimension |
height | number | Height dimension |
unit | string | "in" or "cm" |
quantity | integer | Number of this item to pack (default: 1) |
uprightOnly | boolean | If true, item won't be rotated on its side |
durability | integer | Stacking durability (1-10). Higher = can support more weight on top |
weight | number | Weight per unit (uses weightUnit from request) |
color | string | Hex color for 3D visualization (e.g. "#FF6B35") |
payload | string | Custom data passed through to the response |
Container Object
| Field | Type | Description |
|---|---|---|
name | string | Descriptive label for the container |
length | number | Interior length |
width | number | Interior width |
height | number | Interior height |
unit | string | "in", "cm", or "ft" |
loadingMode | string | "topDown" (default), "frontLoad", "sideLoad" |
payload | string | Custom data passed through to the response |
Error Codes
| Code | Description |
|---|---|
400 | Invalid request body — check required fields and types |
401 | Invalid or missing API key (commercial tier) |
403 | Valid key but plan does not cover this operation — upgrade required |
408 | Packing timed out — reduce item count or complexity |
413 | Request payload too large — reduce the number of items or containers |
429 | Rate limit exceeded — wait and retry |
500 | Internal server error — contact support if this persists |
503 | Service temporarily unavailable — retry after a short delay |
GET
/api/pack/{id}Retrieve a previously stored pack result by ID.
Response fields:
id, createdAt, request, responseError: 404 if the result does not exist or has expired
GET
/api/pack/{id}/container/{index}/svgRender a 2D SVG visualization of a specific container from a pack result.
Response:
image/svg+xmlError: 404 if result or container index not found