For developers · Team plan

Ask Packy from your own code

The same packing engine as the 3D planner, over a small versioned REST API: pack items into a truck, container, pallet or your own space; find which space fits; and keep your team's plans in sync. Sizes are always integer millimetres and weights integer grams.

Quick start

  1. Start the Team plan for your team (pricing). The API is a Team feature.
  2. Open Team → API keys as the team owner, name a key and pick a scope. The key is shown once: we only keep a fingerprint, so a lost key is replaced, not recovered.
  3. Send it as Authorization: Bearer pk_live_….

Pack

curl https://getpacky.space/api/v1/pack \
  -H "Authorization: Bearer pk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "truck-15ft",
    "items": [
      { "name": "Medium box", "dims": { "l": 450, "w": 350, "h": 300 }, "weight": 12000, "qty": 40 },
      { "name": "Sofa", "dims": { "l": 2100, "w": 950, "h": 850 }, "weight": 55000, "qty": 1,
        "constraints": { "floorOnly": true } }
    ]
  }'

Response (trimmed)

{
  "engineVersion": "0.4.0",
  "space": { "id": "truck-15ft", "name": "15ft moving truck", "kind": "truck", "interior": { "l": 4572, "w": 2337, "h": 2184 }, "maxPayload": 2857678 },
  "fits": true,
  "fill": 0.31,
  "placedUnits": 41,
  "totalUnits": 41,
  "totalWeight": 535000,
  "unplaced": [],
  "placements": [ { "itemId": "item-1", "unit": 0, "pos": { "x": 0, "y": 0, "z": 0 }, "dims": { "l": 450, "w": 350, "h": 300 }, "step": 0, "pinned": false } ],
  "violations": [],
  "strategy": "…",
  "ms": 180
}

Endpoints

CallWhat it doesScope
GET /api/v1/spaces
List preset spaces
Every built-in truck, van, container, pallet and storage unit with its usable interior (mm) and payload (g). Use an `id` as `spaceId`.
read
POST /api/v1/pack
Pack items into a space
Runs the Packy packing engine on the server: placements, whether it all fits, and how full the space is. Send `spaceId` (a preset) or a custom `space`. Sizes are integer millimetres and weights integer grams.
read · engine
POST /api/v1/recommend
Which space fits?
Tries the items in each candidate space and ranks them: the smallest one that fits everything first. Defaults to every preset space.
read · engine
GET /api/v1/projects
List your team's projects
Plans owned by the team the key belongs to, newest change first. Never anyone else's.
read
POST /api/v1/projects
Create a project
Send a whole `doc`, or `items` plus a space (and Packy packs it for you). The plan shows up for everyone on the team, with a link to open it in the editor.
write · engine
GET /api/v1/projects/{id}
Get a project
One of the team's projects, including its whole document.
read
PUT /api/v1/projects/{id}
Update a project
Rename and / or replace the document. Send the `version` you last read: if someone saved in between you get a 409 `conflict` carrying the current version.
write
DELETE /api/v1/projects/{id}
Delete a project
Moves the project out of everyone's list (it can be restored by Packy support for a while). Share links of the plan stop working.
write

Every request and response shape is in the OpenAPI document, generated from the same schemas the server validates with, so it can't drift. Import it into Postman, Insomnia or a client generator.

Scopes and limits

  • read: spaces, pack, recommend, list and get projects.
  • write: all of that, plus create, update and delete projects.
  • 120 requests a minute per key; 30 of them may be pack / recommend. See X-RateLimit-* and Retry-After.
  • Up to 200 item lines and 5,000 units per request. The search budget is timeBudgetMs (default 1500, max 5000); the same seed gives the same answer.
  • Keys act as the team: they only ever see and change the team's own plans, never anyone's personal ones.

Errors

Always the same shape, so you can switch on error.code:

HTTP/1.1 400 Bad Request
{ "error": { "code": "invalid_request", "message": "The request body didn't pass validation.",
             "details": [{ "path": "items.0.dims.l", "message": "Too small: expected number to be >0" }],
             "requestId": "req_3f9a1c2b7d4e5a60" } }

unauthorized (401) · forbidden (403) · plan_required (402) · not_found (404) · invalid_request (400) · conflict (409) · payload_too_large (413) · rate_limited (429) · timeout (504) · internal (500)

Selling on Shopify?

The Packy Shopify app turns an order into “fits on 2 pallets or 5 cartons” using your variants' weight and size metafields, and opens the plan in Packy.