Getting Started
Quick Start
Go from zero to a working API call in under 5 minutes.
1. Get Your API Key
- Create a StoaPack account (free tier available)
- Go to your Dashboard
- Click Create API Key and copy it
Include your key in every request as a header:
X-API-Key: your_key_here2. Your First Request
Pack 3 widgets into a small box at a single warehouse. Pick your language:
curl -X POST https://stoapack.stoalogistics.com/api/v1/optimize \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"items": [
{
"item_id": "WIDGET-001",
"width": 6,
"height": 4,
"length": 8,
"weight": 2.5,
"quantity": 3
}
],
"warehouses": [
{
"warehouse_id": "WH-EAST",
"boxes": [
{
"box_id": "SMALL",
"width": 12,
"height": 10,
"length": 14,
"max_weight": 25,
"quantity": 100
}
],
"inventory": {
"WIDGET-001": 10
}
}
],
"units": "in"
}'import requests
response = requests.post(
"https://stoapack.stoalogistics.com/api/v1/optimize",
headers={
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
json={
"items": [
{
"item_id": "WIDGET-001",
"width": 6,
"height": 4,
"length": 8,
"weight": 2.5,
"quantity": 3
}
],
"warehouses": [
{
"warehouse_id": "WH-EAST",
"boxes": [
{
"box_id": "SMALL",
"width": 12,
"height": 10,
"length": 14,
"max_weight": 25,
"quantity": 100
}
],
"inventory": {
"WIDGET-001": 10
}
}
],
"units": "in"
}
)
print(response.json())const response = await fetch(
"https://stoapack.stoalogistics.com/api/v1/optimize",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
body: JSON.stringify({
items: [
{
item_id: "WIDGET-001",
width: 6,
height: 4,
length: 8,
weight: 2.5,
quantity: 3
}
],
warehouses: [
{
warehouse_id: "WH-EAST",
boxes: [
{
box_id: "SMALL",
width: 12,
height: 10,
length: 14,
max_weight: 25,
quantity: 100
}
],
inventory: {
"WIDGET-001": 10
}
}
],
units: "in"
})
}
);
const data = await response.json();
console.log(data);$ch = curl_init("https://stoapack.stoalogistics.com/api/v1/optimize");
$payload = json_encode([
"items" => [
[
"item_id" => "WIDGET-001",
"width" => 6,
"height" => 4,
"length" => 8,
"weight" => 2.5,
"quantity" => 3
]
],
"warehouses" => [
[
"warehouse_id" => "WH-EAST",
"boxes" => [
[
"box_id" => "SMALL",
"width" => 12,
"height" => 10,
"length" => 14,
"max_weight" => 25,
"quantity" => 100
]
],
"inventory" => [
"WIDGET-001" => 10
]
]
],
"units" => "in"
]);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: YOUR_API_KEY"
]
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;3. Understanding the Response
A successful response looks like this (simplified):
{
"packages": [
{
"package_id": "pkg_WH-EAST_SMALL_a1b2c3",
"warehouse_id": "WH-EAST",
"box_id": "SMALL",
"box_dimensions": {
"width": 12,
"height": 10,
"length": 14
},
"items": [
{
"item_id": "WIDGET-001",
"position": { "x": 0, "y": 0, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
},
{
"item_id": "WIDGET-001",
"position": { "x": 6, "y": 0, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
},
{
"item_id": "WIDGET-001",
"position": { "x": 0, "y": 4, "z": 0 },
"dimensions": { "width": 6, "height": 4, "length": 8 },
"rotated": false,
"weight": 2.5
}
],
"total_weight": 7.5,
"volume_utilization": 0.41
}
],
"summary": {
"total_packages": 1,
"total_items_packed": 3,
"warehouses_used": ["WH-EAST"]
},
"unfitted_items": []
}Key fields
| packages | Array of packed boxes. Each package contains its items with exact 3D placement coordinates. |
| package_id | Format: pkg_{warehouse}_{box}_{random}. Uniquely identifies each packed box. |
| position | The x, y, z coordinates where the item is placed inside the box (origin is the box corner). |
| rotated | Whether the item was rotated to fit. StoaPack tries all valid orientations. |
| volume_utilization | How efficiently the box is filled (0 to 1). Higher is better. |
| summary | Aggregate stats: total packages, items packed, warehouses used. |
| unfitted_items | Items that couldn't fit in any available box. Empty means everything packed successfully. |