API Reference

# Truck Packer REST API – AI Agent Skill

You are an AI agent with access to the Truck Packer REST API. Use this reference to make API calls on behalf of the user.

## Authentication

All requests require a Bearer token:

```
Authorization: Bearer tp_<api-key>
```

Generate keys from **Settings → API Keys** in the Truck Packer app.

## Base URL

```
https://steady-beagle-345.convex.site/api/v1
```

## Conventions

- Dimensions: **meters**
- Weights: **kilograms**
- Rate limit: 200 req/min, 300 burst
- \`orgId\` is inferred from the API key — never include it in request bodies

---

## Cases

Cases are box types that can be loaded into containers.

### List Cases

```
GET /api/v1/cases
```

### Get Case by ID

```
GET /api/v1/cases/:id
```

### Create Case

```
POST /api/v1/cases
Content-Type: application/json

{
  "name": "string (required)",
  "dx": "number (required) — length in meters",
  "dy": "number (required) — width in meters",
  "dz": "number (required) — height in meters",
  "canRotate3d": "boolean (required)",
  "categoryId": "string (required)",
  "description": "string (optional)",
  "manufacturer": "string (optional)",
  "weight": "number (optional) — kilograms"
}
```

### Update Case

```
PUT /api/v1/cases/:id
Content-Type: application/json

{
  "name": "string",
  "description": "string",
  "manufacturer": "string",
  "weight": "number",
  "dx": "number",
  "dy": "number",
  "dz": "number",
  "canRotate3d": "boolean",
  "categoryId": "string"
}
```

All fields optional — include only what you want to change.

### Delete Case

```
DELETE /api/v1/cases/:id
```

---

## Case Categories

Categories group cases by type with a color for visual identification.

### List Case Categories

```
GET /api/v1/case-categories
```

### Create Case Category

```
POST /api/v1/case-categories
Content-Type: application/json

{
  "name": "string (required)",
  "colorHex": "string (required) — e.g. '#FF4444'"
}
```

### Update Case Category

```
PUT /api/v1/case-categories/:id
Content-Type: application/json

{
  "name": "string",
  "colorHex": "string"
}
```

### Delete Case Category

```
DELETE /api/v1/case-categories/:id
```

---

## Containers

Containers are the trucks, trailers, or shipping containers that cases are loaded into.

### List Containers

```
GET /api/v1/containers
```

### Get Container by ID

```
GET /api/v1/containers/:id
```

### Create Container

```
POST /api/v1/containers
Content-Type: application/json

{
  "name": "string (required)",
  "type": "string (required) — one of: dry_container, boxcar, flatbed_trailer, step_deck_trailer, dry_van_trailer, reefer_van_trailer, box_truck, uld",
  "dx": "number (required) — length in meters",
  "dy": "number (required) — width in meters",
  "dz": "number (required) — height in meters",
  "description": "string (optional)",
  "code": "string (optional)",
  "payloadCapacity": "number (optional) — kilograms"
}
```

### Update Container

```
PUT /api/v1/containers/:id
Content-Type: application/json

{
  "name": "string",
  "description": "string",
  "code": "string",
  "type": "string",
  "dx": "number",
  "dy": "number",
  "dz": "number",
  "payloadCapacity": "number"
}
```

### Delete Container

```
DELETE /api/v1/containers/:id
```

---

## Packs

Packs are loading plans — workspaces where cases are arranged inside containers.

### List Packs

```
GET /api/v1/packs
```

### Get Pack by ID

```
GET /api/v1/packs/:id
```

### Get Pack Entities

```
GET /api/v1/packs/:id/entities
```

Returns all entities (cases, containers, groups) within a pack.

### Create Pack

```
POST /api/v1/packs
Content-Type: application/json

{
  "name": "string (optional)",
  "folderId": "string (optional)"
}
```

### Delete Pack

```
DELETE /api/v1/packs/:id
```

Permanently deletes the pack and all its entities, export views, and thumbnails.

---

## Entities

Entities are scene graph nodes within a pack — cases, containers, and groups positioned in 3D space.

### Get Entities by Pack ID

```
GET /api/v1/entities?packId=PACK_ID
```

The \`packId\` query parameter is required.

### Batch Create Entities

```
POST /api/v1/entities:batchCreate
Content-Type: application/json

{
  "entities": [
    {
      "name": "string (required)",
      "type": "string (required) — case | container | group",
      "packId": "string (required)",
      "visible": "boolean (required)",
      "childrenIds": "string[] (required) — empty array for leaf nodes",
      "position": "{ x, y, z } (required) — meters",
      "quaternion": "{ x, y, z, w } (required) — use {0,0,0,1} for no rotation",
      "size": "{ x, y, z } (required) — meters",
      "caseData": "{ weight?, manufacturer?, canRotate3d, categoryId } (required when type=case)",
      "containerData": "{ type, payloadCapacity? } (required when type=container)",
      "groupData": "{ colorHex } (required when type=group)"
    }
  ]
}
```

> **Important:** You must include the matching type-specific data object for each entity. For example, an entity with \`type: "case"\` requires \`caseData\`. Entities missing their type-specific data will be silently dropped from the batch.

### Batch Update Entities

```
POST /api/v1/entities:batchUpdate
Content-Type: application/json

{
  "packId": "string (required)",
  "entities": [
    {
      "id": "string (required)",
      "name": "string",
      "description": "string",
      "visible": "boolean",
      "position": "{ x, y, z }",
      "quaternion": "{ x, y, z, w }",
      "size": "{ x, y, z }",
      "caseData": "object",
      "containerData": "object",
      "groupData": "object"
    }
  ]
}
```

Only include fields you want to change.

### Batch Delete Entities

```
POST /api/v1/entities:batchDelete
Content-Type: application/json

{
  "packId": "string (required)",
  "ids": ["ENTITY_ID_1", "ENTITY_ID_2"]
}
```

Children are deleted recursively.

---

## Common Workflows

### Import cases from an external system
1. \`POST /api/v1/case-categories\` — create categories first
2. \`POST /api/v1/cases\` — create cases with the category IDs

### Build a load plan programmatically
1. \`POST /api/v1/packs\` — create a pack
2. \`POST /api/v1/entities:batchCreate\` — batch create containers and cases with positions

### Sync inventory
1. \`GET /api/v1/cases\` — fetch current cases
2. \`PUT /api/v1/cases/:id\` — update changed cases
3. \`POST /api/v1/cases\` — create new cases
4. \`DELETE /api/v1/cases/:id\` — remove deleted cases

---

## Error Responses

All errors return JSON:

```json
{
  "success": false,
  "error": "Error message describing what went wrong"
}
```

| Status | Meaning |
|--------|---------|
| 401 | Missing or invalid API key |
| 404 | Resource not found |
| 422 | Validation error (check required fields) |
| 429 | Rate limit exceeded |
| 500 | Server error |