API Documentation

Reference documentation for the Logistics Engine optimization service (routing + loading).

Base URL: https://api.stower.dev

Generated: 2026-01-04 00:52:43

Authentication

Authenticate requests using an API key in either header:

Authorization: Bearer <API_KEY>
X-API-Key: <API_KEY>

Idempotency

For safe retries on submissions, send an idempotency header:

Idempotency-Key: <unique value>
X-Idempotency-Key: <unique value>

HTTP response codes and errors

Code	Meaning
200	Success
400	Bad request / validation error
401	Missing/invalid credentials
403	Insufficient role/permissions
404	Not found
409	Conflict (e.g., idempotency key reused with different payload)
429	Rate limit / tenant concurrency admission rejected
503	Service unavailable / draining

Error format is JSON:

{
  "detail": "human-readable message"
}

Reference

Parameter groups used by the optimization API.

Policies

Feature flags and behavior knobs that influence routing/packing and solver strategy. Pass under policies in requests (where supported).

Key	Type	Required	Description
aisle_priority	boolean	No	Bias routing/servicing decisions using aisle or service-order preferences when applicable.
center_balance_mode	boolean	No
enable_voxel_nesting	boolean	No
fragile_separation	boolean	No
objective	object	No
objective_name	string	No
rear_load_bias	boolean	No	Bias packing toward rear-loading preference (may affect packing efficiency).
spread_items	boolean	No
strap_priority	boolean	No
voxel_pitch_in	number	No
vrp_lns	object	No	Optional VRP Large Neighborhood Search (LNS) tuning object. Also accepted as top-level config.vrp_lns and mirrored into policies.vrp_lns.

Example

{
  "policies": {
    "rear_load_bias": true,
    "center_balance_mode": true,
    "spread_items": true,
    "aisle_priority": true,
    "strap_priority": true,
    "fragile_separation": true,
    "enable_voxel_nesting": true,
    "voxel_pitch_in": 2.0,
    "objective_name": "minimize_miles",
    "objective": {
      "name": "minimize_miles",
      "truck_fixed_cost_miles": 60.0,
      "weights": {
        "total_miles": 1.0,
        "trucks_used": 8.0,
        "unplaced_items": 250.0
      }
    }
  }
}

Objective

Controls the optimization objective (cost function) and related weights/presets. Pass under objective in requests (where supported).

Key	Type	Required
name	string	No
truck_fixed_cost_miles	number	No
weights	object	No

Example

{
  "objective": {
    "truck_fixed_cost_miles": 60.0,
    "weights": {
      "total_miles": 1.0,
      "trucks_used": 8.0,
      "unplaced_items": 250.0,
      "weight_distribution_penalty": 3.0,
      "fragile_violation_penalty": 6.0
    }
  }
}

Metaheuristic

Advanced solver settings (GA, local search, etc.). Usually for expert tuning. Pass under metaheuristic in requests (where supported).

Key	Type	Required
elite_fraction	number	No
enable_ga	boolean	No
generations	integer	No
mutation_rate	number	No
population_size	integer	No

Example

{
  "metaheuristic": {
    "enable_ga": true,
    "population_size": 12,
    "generations": 6,
    "elite_fraction": 0.25,
    "mutation_rate": 0.35
  }
}

Safety profile

Safety preferences for routing/packing (e.g., stability, fragile handling). Pass under safety_profile in requests (where supported).

Key	Type	Required
allowed_tags	array	No
max_height_ft	number	No
max_vehicle_length_ft	integer	No
oversize_thresholds	object	No
prohibited_access_flags	array	No
prohibited_road_tags_for_hazmat	array	No

Example

{
  "safety_profile": {
    "max_vehicle_length_ft": 26,
    "max_height_ft": 12.5,
    "allowed_tags": [
      "highway",
      "arterial",
      "industrial",
      "residential"
    ],
    "prohibited_access_flags": [
      "no_26ft"
    ],
    "prohibited_road_tags_for_hazmat": [
      "tunnel",
      "bridge_restricted"
    ],
    "oversize_thresholds": {
      "max_single_piece_weight_lbs": 2500.0,
      "max_single_piece_length_in": 192.0,
      "max_single_piece_width_in": 96.0,
      "max_single_piece_height_in": 84.0,
      "near_limit_pct": 0.92,
      "permit_weight_lbs": 5000.0,
      "permit_length_in": 240.0,
      "permit_width_in": 102.0,
      "permit_height_in": 96.0
    }
  }
}

Constraints

Hard/soft constraints applied during routing/packing. Pass under constraints in requests (where supported).

Key	Type	Required
bottom_layer	boolean	No
front_load	boolean	No
rear_load	boolean	No
top_layer	boolean	No
z_band	string	No

Example

{
  "constraints": {
    "bottom_layer": true,
    "top_layer": false,
    "front_load": false,
    "rear_load": true,
    "z_band": "bottom"
  }
}

Hazmat

Hazardous materials configuration and compatibility rules. Pass under hazmat in requests (where supported).

Key	Type	Required
class	object	No
enabled	boolean	No
incompatible_with	array	No
packing_group	object	No
requires_separation_in	number	No
un_number	object	No

Example

{
  "hazmat": {
    "enabled": false,
    "class": null,
    "un_number": null,
    "packing_group": null,
    "incompatible_with": [],
    "requires_separation_in": 6.0
  }
}

Policies patch

Patch-style overrides applied on top of effective policies (scenario overrides). Pass under policies_patch in requests (where supported).

Key	Type	Required
center_balance_mode	boolean	No
fragile_separation	boolean	No
objective_name	string	No
rear_load_bias	boolean	No

Zones

Geographic zones, service areas, and zone-based constraints. Pass under zones in requests (where supported).

Key	Type	Required	Default	Description
temperature	string	No

Example

{
  "zones": {
    "temperature": "ambient"
  }
}

Public API

POST /optimize Optimize (sync)

▾

Run routing + packing synchronously. Best for smaller payloads or when you need an immediate response.

Auth

Query

_job_id, _run_id, _bypass_cache (default false)

Authorization: Bearer or X-API-Key

Request body

OptimizeRequest

Reference

Policies · Objective · Metaheuristic · Safety profile · Constraints · Hazmat · Policies patch · Zones

💡 Use Idempotency-Key for safe retries.

💡 For large payloads, prefer /optimize_async.

Try it

Base URL API Key

Request JSON

Runs in your browser (CORS must allow it).

POST /optimize/validate Validate request

▾

Validate an OptimizeRequest without running the solver.

Auth

Authorization: Bearer or X-API-Key

Request body

OptimizeRequest

Reference

Policies · Objective · Metaheuristic · Safety profile · Constraints · Hazmat · Policies patch · Zones

💡 Useful in CI/integration tests to catch schema issues early.

Try it

Base URL API Key

Request JSON

Runs in your browser (CORS must allow it).

POST /optimize_async Optimize (async)

▾

Submit an optimization job for asynchronous processing. Returns a job_id.

Auth

Authorization: Bearer or X-API-Key

Request body

OptimizeRequest

Reference

Policies · Objective · Metaheuristic · Safety profile · Constraints · Hazmat · Policies patch · Zones

💡 Poll status and result endpoints.

💡 Use Idempotency-Key for safe retries of submissions.

Try it

Base URL API Key

Request JSON

Runs in your browser (CORS must allow it).

GET /optimize_async/status/{job_id} Async status

▾

Get state/stage/progress snapshot for an async job.

Auth

Path

job_id

Authorization: Bearer or X-API-Key

GET /optimize_async/result/{job_id} Async result

▾

Fetch final result for a completed async job (or a status object if still running).

Auth

Path

job_id

Authorization: Bearer or X-API-Key

GET /optimize_async/payload/{job_id} Async payload

▾

Fetch the original (redacted) request payload for an async job (if stored).

Auth

Authorization: Bearer or X-API-Key

Path

job_id

GET /optimize_async/events/{job_id} Async events (SSE)

▾

Server-Sent Events stream of progress updates.

Auth

Path

job_id

Authorization: Bearer or X-API-Key

💡 Consumes as text/event-stream.

POST /optimize_async/cancel/{job_id} Cancel async job

▾

Request cancellation of an in-progress job (best-effort).

Auth

Path

job_id

Authorization: Bearer or X-API-Key

POST /optimize_scenarios Optimize scenarios

▾

Run multiple scenario variants and return per-scenario results.

Auth

Authorization: Bearer or X-API-Key

Request body

OptimizeScenariosRequest

Reference

Policies · Objective · Metaheuristic · Safety profile · Constraints · Hazmat · Policies patch · Zones

💡 Supports legacy shapes (vehicles/orders aliases) and optional RFC6902 jsonpatch.

💡 Alias: /optimize-scenarios

Try it

Base URL API Key

Request JSON

{
  "base_request": {
    "config": {
      "api_key": "test_api_key_123",
      "depot_address": "350 5th Ave, New York, NY 10118",
      "depot_lat": 40.7484,
      "depot_lng": -73.9857,
      "travel_mode": "driving",
      "unit_system": "imperial",
      "timezone": "America/New_York",
      "objective_name": "minimize_miles",
      "objective": {
        "truck_fixed_cost_miles": 60.0,
        "weights": {
          "total_miles": 1.0,
          "trucks_used": 8.0,
          "unplaced_items": 250.0,
          "weight_distribution_penalty": 3.0,
          "fragile_violation_penalty": 6.0
        }
      },
      "travel_matrix": {
        "provider": "haversine",
        "osrm_base_url": "https://router.project-osrm.org",
        "osrm_profile": "driving",
        "traffic": true,
        "departure_time": "2026-01-02T08:00:00-05:00",
        "routing_preference": "TRAFFIC_AWARE",
        "timeout_sec": 12.0,
        "fallback_to_haversine": true,
        "max_elements_per_request": 625,
        "cache_ttl_sec": 7200,
        "cache_max_entries": 50000
      },
      "google_api_key": "TEST_GOOGLE_KEY",
      "seed": 12345,
      "webhook_url": "https://example.com/webhook",
      "async_stop_threshold": 10,
      "two_man_lift_enabled": true,
      "two_man_lift_threshold_lbs": 100.0,
      "break_rules": {
        "mandatory_break_duration": 1800,
        "drive_time_before_break": 10800
      },
      "enforce_geometry": true,
      "priority_mode": "hard",
      "lifo_mode": "hard",
      "securement_checks_enabled": true,
      "securement_default_strap_wll_lbs": 2500.0,
      "time_window_mode": "soft",
      "soft_tw_penalty_per_minute": 10,
      "policies": {
        "rear_load_bias": true,
        "center_balance_mode": true,
        "spread_items": true,
        "aisle_priority": true,
        "strap_priority": true,
        "fragile_separation": true,
        "enable_voxel_nesting": true,
        "voxel_pitch_in": 2.0,
        "objective_name": "minimize_miles",
        "objective": {
          "name": "minimize_miles",
          "truck_fixed_cost_miles": 60.0,
          "weights": {
            "total_miles": 1.0,
            "trucks_used": 8.0,
            "unplaced_items": 250.0
          }
        }
      },
      "auto_tuning": true,
      "max_auto_passes": 2,
      "debug": true,
      "metaheuristic": {
        "enable_ga": true,
        "population_size": 12,
        "generations": 6,
        "elite_fraction": 0.25,
        "mutation_rate": 0.35
      },
      "quality_weights": {
        "routing_weight": 0.55,
        "loading_weight": 0.45
      },
      "include_feasibility_explanations": true,
      "include_actionable_recommendations": true
    },
    "vehicles": [
      {
        "truck_id": "T26-001",
        "truck_type": "box-26",
        "start_location": "350 5th Ave, New York, NY 10118",
        "start_time": "08:00",
        "crew_size": 2,
        "dims": {
          "l": 312.0,
          "w": 96.0,
          "h": 96.0
        },
        "max_miles": 180.0,
        "max_duration": 36000,
        "max_stops": 30,
        "max_cargo_weight": 12000.0,
        "max_cargo_volume": 1400.0,
        "trailer_profile": "box-26",
        "has_liftgate": true,
        "has_pallet_jack": true,
        "has_dolly": true,
        "dock_height_mode": "either",
        "loading_sides": [
          "rear",
          "side"
        ],
        "safety_profile": {
          "max_vehicle_length_ft": 26,
          "max_height_ft": 12.5,
          "allowed_tags": [
            "highway",
            "arterial",
            "industrial",
            "residential"
          ],
          "prohibited_access_flags": [
            "no_26ft"
          ],
          "prohibited_road_tags_for_hazmat": [
            "tunnel",
            "bridge_restricted"
          ],
          "oversize_thresholds": {
            "max_single_piece_weight_lbs": 2500.0,
            "max_single_piece_length_in": 192.0,
            "max_single_piece_width_in": 96.0,
            "max_single_piece_height_in": 84.0,
            "near_limit_pct": 0.92,
            "permit_weight_lbs": 5000.0,
            "permit_length_in": 240.0,
            "permit_width_in": 102.0,
            "permit_height_in": 96.0
          }
        },
        "hazmat_profile": {
          "enabled": true,
          "allowed_classes": [
            "3",
            "8"
          ],
          "max_hazmat_weight": 600.0
        },
        "zones": {
          "temperature": "ambient"
        }
      },
      {
        "truck_id": "T53-001",
        "truck_type": "dry-van-53",
        "start_location": "350 5th Ave, New York, NY 10118",
        "start_time": "07:30",
        "crew_size": 1,
        "dims": {
          "l": 636.0,
          "w": 100.0,
          "h": 110.0
        },
        "max_miles": 450.0,
        "max_duration": 43200,
        "max_stops": 60,
        "max_cargo_weight": 34000.0,
        "max_cargo_volume": null,
        "trailer_profile": "dry-van-53",
        "has_liftgate": false,
        "has_pallet_jack": false,
        "has_dolly": false,
        "dock_height_mode": "dock",
        "loading_sides": [
          "rear"
        ],
        "safety_profile": {
          "max_vehicle_length_ft": 53,
          "max_height_ft": 13.5,
          "allowed_tags": [
            "highway",
            "arterial",
            "industrial"
          ],
          "prohibited_access_flags": [
            "no_53ft"
          ],
          "prohibited_road_tags_for_hazmat": [
            "tunnel",
            "bridge_restricted"
          ],
          "oversize_thresholds": {
            "max_single_piece_weight_lbs": 4000.0,
            "max_single_piece_length_in": 240.0,
            "max_single_piece_width_in": 96.0,
            "max_single_piece_height_in": 96.0,
            "near_limit_pct": 0.92,
            "permit_weight_lbs": 8000.0,
            "permit_length_in": 360.0,
            "permit_width_in": 102.0,
            "permit_height_in": 108.0
          }
        },
        "hazmat_profile": {
          "enabled": false,
          "allowed_classes": [],
          "max_hazmat_weight": 1000.0
        },
        "zones": {
          "temperature": "ambient"
        }
      }
    ],
    "orders": [
      {
        "job_id": 101,
        "priority": 2,
        "stops": [
          {
            "stop_id": "S-101-P1",
            "type": "pickup",
            "address": "1 Liberty Island, New York, NY 10004",
            "lat": 40.6892,
            "lng": -74.0445,
            "earliest": "2026-01-02T08:30:00-05:00",
            "latest": "2026-01-02T10:30:00-05:00",
            "service_time_sec": 900,
            "items": [],
            "pickup_delivery_id": "PD-101",
            "safety_tags": [
              "industrial"
            ],
            "access_restrictions": [],
            "requires_liftgate": null,
            "requires_pallet_jack": null,
            "requires_dolly": null,
            "dock_height": "ground",
            "loading_side": "rear"
          },
          {
            "stop_id": "S-101-D1",
            "type": "delivery",
            "address": "200 Central Park West, New York, NY 10024",
            "lat": 40.7813,
            "lng": -73.9735,
            "earliest": "2026-01-02T11:00:00-05:00",
            "latest": "2026-01-02T14:30:00-05:00",
            "service_time_sec": 1200,
            "items": [
              {
                "item_id": "SOFA-3SEAT-001",
                "weight": 180.0,
                "volume": 90.0,
                "dims": {
                  "l": 84.0,
                  "w": 38.0,
                  "h": 34.0
                },
                "item_class": "upholstery",
                "stackable": false,
                "is_top_flat": false,
                "fragile": false,
                "max_stack_weight": 0.0,
                "max_tier": 1,
                "position_constraint": "bottom",
                "allowed_orientations": [
                  "upright"
                ],
                "tilt_modes": [
                  "upright"
                ],
                "strap_required": true,
                "assembly_id": "LIVING-SET-A",
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": false,
                "is_nestable": false,
                "can_nest_with": [],
                "job_id": 101,
                "stop_id": "S-101-D1",
                "stop_seq_index": 1,
                "stack_group_id": null,
                "stack_members": null,
                "hazmat": {
                  "enabled": false,
                  "class": null,
                  "un_number": null,
                  "packing_group": null,
                  "incompatible_with": [],
                  "requires_separation_in": 6.0
                },
                "constraints": {
                  "bottom_layer": true,
                  "top_layer": false,
                  "front_load": false,
                  "rear_load": true,
                  "z_band": "bottom"
                },
                "temperature_zone": "ambient"
              },
              {
                "item_id": "TABLE-GLASS-002",
                "weight": 120.0,
                "volume": 40.0,
                "dims": {
                  "l": 60.0,
                  "w": 36.0,
                  "h": 30.0
                },
                "item_class": "glass",
                "stackable": false,
                "is_top_flat": true,
                "fragile": true,
                "max_stack_weight": 0.0,
                "max_tier": 1,
                "position_constraint": "rear",
                "allowed_orientations": [
                  "upright",
                  "rotated"
                ],
                "tilt_modes": [
                  "upright",
                  "side"
                ],
                "strap_required": true,
                "assembly_id": null,
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": false,
                "is_nestable": false,
                "can_nest_with": [],
                "job_id": 101,
                "stop_id": "S-101-D1",
                "stop_seq_index": 1,
                "stack_group_id": null,
                "stack_members": null,
                "hazmat": {
                  "enabled": false,
                  "class": null,
                  "un_number": null,
                  "packing_group": null,
                  "incompatible_with": [],
                  "requires_separation_in": 6.0
                },
                "constraints": {
                  "bottom_layer": false,
                  "top_layer": true,
                  "front_load": false,
                  "rear_load": false,
                  "z_band": "top"
                },
                "temperature_zone": "ambient"
              }
            ],
            "pickup_delivery_id": "PD-101",
            "safety_tags": [
              "residential"
            ],
            "access_restrictions": [
              "no_53ft"
            ],
            "requires_liftgate": true,
            "requires_pallet_jack": false,
            "requires_dolly": true,
            "dock_height": "ground",
            "loading_side": "either"
          }
        ],
        "exclusive_truck_ids": [
          "T26-001"
        ]
      },
      {
        "job_id": 202,
        "priority": 1,
        "stops": [
          {
            "stop_id": "S-202-D1",
            "type": "delivery",
            "address": "10 Exchange Pl, Jersey City, NJ 07302",
            "lat": 40.7163,
            "lng": -74.0334,
            "earliest": "2026-01-02T09:00:00-05:00",
            "latest": "2026-01-02T12:00:00-05:00",
            "service_time_sec": 600,
            "items": [
              {
                "item_id": "PAINT-5GAL-UN1263",
                "weight": 55.0,
                "volume": 2.0,
                "dims": {
                  "l": 14.0,
                  "w": 14.0,
                  "h": 18.0
                },
                "item_class": "hazmat",
                "stackable": true,
                "is_top_flat": true,
                "fragile": false,
                "max_stack_weight": 500.0,
                "max_tier": 4,
                "position_constraint": "none",
                "allowed_orientations": [
                  "upright",
                  "rotated"
                ],
                "tilt_modes": [
                  "upright"
                ],
                "strap_required": false,
                "assembly_id": null,
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": true,
                "is_nestable": true,
                "can_nest_with": [
                  "hazmat",
                  "generic"
                ],
                "job_id": 202,
                "stop_id": "S-202-D1",
                "stop_seq_index": 0,
                "stack_group_id": "STACK-PAINT-1",
                "stack_members": [
                  "PAINT-5GAL-UN1263"
                ],
                "hazmat": {
                  "enabled": true,
                  "class": "3",
                  "un_number": "UN1263",
                  "packing_group": "II",
                  "incompatible_with": [
                    "5.1"
                  ],
                  "requires_separation_in": 12.0
                },
                "constraints": {
                  "bottom_layer": true,
                  "top_layer": false,
                  "front_load": true,
                  "rear_load": false,
                  "z_band": null
                },
                "temperature_zone": "ambient"
              }
            ],
            "pickup_delivery_id": null,
            "safety_tags": [
              "industrial"
            ],
            "access_restrictions": [],
            "requires_liftgate": false,
            "requires_pallet_jack": true,
            "requires_dolly": false,
            "dock_height": "dock",
            "loading_side": "rear"
          }
        ],
        "exclusive_truck_ids": null
      }
    ]
  },
  "scenarios": [
    {
      "scenario_id": "S1_obj_min_trucks",
      "label": "Minimize trucks used",
      "objective_name": "minimize_trucks",
      "policies_patch": {
        "rear_load_bias": false,
        "center_balance_mode": true
      }
    },
    {
      "scenario_id": "S2_soft_tw_no_ga",
      "label": "Soft TW + GA off, reduce penalty",
      "policies_patch": {
        "objective_name": "maximize_items_placed",
        "fragile_separation": true
      },
      "jsonpatch": [
        {
          "op": "replace",
          "path": "/config/time_window_mode",
          "value": "soft"
        },
        {
          "op": "replace",
          "path": "/config/soft_tw_penalty_per_minute",
          "value": 2
        },
        {
          "op": "replace",
          "path": "/config/metaheuristic/enable_ga",
          "value": false
        },
        {
          "op": "replace",
          "path": "/trucks/0/max_miles",
          "value": 120.0
        }
      ]
    }
  ],
  "options": {
    "include_plans": true,
    "max_scenarios": 8
  }
}

Runs in your browser (CORS must allow it).

Tenant

GET /tenant/me Tenant identity

▾

Return resolved tenant identity and policy snapshot.

Auth

Authorization: Bearer or X-API-Key

GET /tenant/usage Tenant usage

▾

Return tenant usage metrics and quota/capacity limits.

Auth

Query

days (default 30)

Authorization: Bearer or X-API-Key

GET /tenant/audit Tenant audit

▾

Return tenant-scoped audit events.

Auth

Query

days (default 30), top_n (default 10)

Authorization: Bearer or X-API-Key

GET /runs Runs list

▾

List recent optimization runs for the resolved tenant (most recent first).

Auth

Authorization: Bearer or X-API-Key

Query

limit (default 50), since_ms, until_ms

GET /runs/{run_id} Run detail

▾

Fetch a decision-traceability record for a specific run_id (tenant-scoped).

Auth

Authorization: Bearer or X-API-Key

Path

run_id

GET /runs/{run_id}/explain Run explain

▾

Fetch explainability artifacts for a run (e.g., unassigned stops / unplaced items).

Auth

Authorization: Bearer or X-API-Key

Path

run_id

Query

limit (default 1000), artifact_type

POST /runs/{run_id}/replay Run replay

▾

Re-run a prior optimization run (server-side replay) using the stored payload/snapshot (tenant-scoped).

Auth

Authorization: Bearer or X-API-Key

Path

run_id

GET /audit Audit events

▾

Append-only audit event stream for the resolved tenant (filterable).

Auth

Authorization: Bearer or X-API-Key

Query

limit (default 200), since_ms, until_ms, action, request_id, run_id, user_id

Org & Membership

Endpoints for managing organizations, user memberships, and inter-org relationships. Orgs can be of type THREE_PL, SHIPPER, or CARRIER. Relationships between orgs (e.g. a 3PL linking to a shipper) use a two-step invite/approve flow. User memberships use a single invite/accept flow. All write endpoints require tenant:write scope; read endpoints require tenant:read.

POST /org/tenants Create org

▾

Create a new organization. org_type must be one of THREE_PL, SHIPPER, or CARRIER. Invite policies default to MANUAL.

Auth

Authorization: Bearer or X-API-Key — scope tenant:write

Body

application/json — OrgCreateRequest

Fields

name, org_type, invite_policy_shipper (AUTO_ACCEPT|MANUAL), invite_policy_carrier, plus contact fields: email, phone, address, city, state, zipCode, country (ISO-3), lat, lng

GET /org/auth/whoami Auth whoami

▾

Return the resolved actor identity for the current request — useful for verifying which user ID is being inferred from the auth token.

Auth

Authorization: Bearer or X-API-Key — scope tenant:read

POST /org/memberships/invite Invite member

▾

Invite a user to join an org by email. The invitee receives a token they must submit to /org/invites/accept. role is granted upon acceptance.

Auth

Authorization: Bearer or X-API-Key — scope tenant:write

Body

application/json — MembershipInviteRequest

Fields

POST /org/memberships/list List members

▾

Return all members of an org with their roles and statuses.

Auth

Authorization: Bearer or X-API-Key — scope tenant:read

Body

application/json — {"org_id": "..."}

POST /org/relationships/invite Invite relationship

▾

Initiate a relationship between two orgs (e.g. a 3PL linking to a shipper or carrier). The invitee org must approve via /org/relationships/approve unless their invite_policy is AUTO_ACCEPT.

Auth

Authorization: Bearer or X-API-Key — scope tenant:write

Body

application/json — RelationshipInviteRequest

Fields

from_org_id, to_org_id, relationship_kind (SHIPPER|CARRIER), invitee_email, inviter_user_id (optional)

POST /org/relationships/approve Approve relationship

▾

Approve a pending inter-org relationship invite. Only needed when the invitee org's invite_policy is MANUAL.

Auth

Authorization: Bearer or X-API-Key — scope tenant:write

Body

application/json — ApproveRelationshipRequest

Fields

from_org_id, to_org_id, relationship_kind, approver_user_id (optional)

POST /org/invites/accept Accept invite

▾

Accept a membership or relationship invite using the token from the invite response. Works for both USER_MEMBERSHIP and TENANT_RELATIONSHIP invite kinds.

Auth

Authorization: Bearer or X-API-Key — scope tenant:write

Body

application/json — AcceptInviteRequest

Fields

token, acceptor_email, acceptor_user_id (optional — resolved from auth if omitted)

Reseller

Endpoints for reseller tenants to provision and manage customer sub-tenants and their API keys. All endpoints require the reseller:admin scope and authenticate via the reseller's own API key. Child tenant key prefixes must start with {reseller_prefix}__.

GET /reseller/tenants List customer tenants

▾

Return all customer tenants owned by the authenticated reseller, scoped to the reseller prefix namespace.

Auth

X-API-Key with reseller:admin scope

POST /reseller/tenants Create customer tenant

▾

Create or upsert a customer tenant under the reseller namespace. Entitlements are automatically clamped to the reseller policy. key_prefix must start with {reseller_prefix}__.

Auth

X-API-Key with reseller:admin scope

Body

application/json — ResellerTenantCreate

POST /reseller/tenants/{key_prefix}/suspend Set tenant status

▾

Update the status of a customer tenant (active, suspended, or disabled). The tenant must be in the reseller namespace.

Auth

X-API-Key with reseller:admin scope

Path

key_prefix

Body

application/json — ResellerTenantSuspend

POST /reseller/tenants/{key_prefix}/keys Create customer API key

▾

Issue a new API key for a customer tenant. Scopes are clamped to the tenant's allowed_scopes policy. Requires the API key store to be enabled.

Auth

X-API-Key with reseller:admin scope

Path

key_prefix

Body

application/json — ResellerKeyCreate

Ops

GET /health Health

▾

Liveness endpoint.

Auth

Authorization: Bearer or X-API-Key

GET /readyz Readiness

▾

Readiness endpoint.

Auth

Authorization: Bearer or X-API-Key

GET /metrics Prometheus metrics

▾

Prometheus text exposition format.

Auth

Authorization: Bearer or X-API-Key

GET /objectives Objectives

▾

List supported objective presets.

Auth

Authorization: Bearer or X-API-Key

GET /capacity Capacity

▾

Capacity snapshot (slots, draining state).

Auth

Authorization: Bearer or X-API-Key

Model definitions

Schema reference derived from Pydantic models.

OptimizeRequest

Field	Type	Required
config	OptimizationConfig	Yes
trucks	List[Truck]	Yes
jobs	List[Job]	Yes

OptimizeScenariosRequest

Field	Type	Required	Description
config	OptimizationConfig	Yes
trucks	List[Truck]	Yes
jobs	List[Job]	Yes
scenarios	List[ScenarioSpec]	Yes	List of what-if scenarios to evaluate.
options	Map[string, object]	No	Optional controls, e.g. {include_plans:false, max_scenarios:8}.

OptimizationConfig

Field	Type	Required	Default
api_key	string	Yes
depot_address	string	Yes
depot_lat	number	Yes
depot_lng	number	Yes
async_stop_threshold	integer	No	40
auto_tuning	boolean	No	false
break_rules	Map[string, integer]	No
debug	boolean	No	false
enforce_geometry	boolean	No	true
feasibility_prover_core_seconds	number	No	1.0
feasibility_prover_enabled	boolean	No	true
feasibility_prover_extract_core	boolean	No	true
feasibility_prover_include_witness	boolean	No	false
feasibility_prover_max_items	integer	No	18
feasibility_prover_max_seconds	number	No	2.0
google_api_key	string \| null	No
include_actionable_recommendations	boolean	No	true
include_feasibility_explanations	boolean	No	true
lifo_mode	string	No	"soft"
max_auto_passes	integer	No	1
metaheuristic	Map[string, object]	No
objective	object \| null	No
objective_name	string \| null	No
policies	Map[string, object]	No
priority_mode	string	No	"soft"
quality_weights	Map[string, number] \| null	No
securement_checks_enabled	boolean	No	false
securement_default_strap_wll_lbs	number	No	3333.0
seed	integer \| null	No
soft_tw_penalty_per_minute	integer	No	5
time_window_mode	string	No	"hard"
timezone	string	No	"America/New_York"
travel_matrix	TravelMatrixConfig	No
travel_mode	string	No	"driving"
two_man_lift_enabled	boolean	No	false
two_man_lift_threshold_lbs	number	No	75.0
unit_system	string	No	"imperial"
vrp_lns	Map[string, object] \| null	No
webhook_url	string \| null	No

TravelMatrixConfig

Field	Type	Required	Default
cache_max_entries	integer	No	200000
cache_ttl_sec	integer	No	21600
departure_time	string \| null	No
fallback_to_haversine	boolean	No	true
max_elements_per_request	integer	No	625
osrm_base_url	string	No	"https://router.project-osrm.org"
osrm_profile	string \| null	No
provider	string	No	"haversine"
routing_preference	string \| null	No
timeout_sec	number	No	15.0
traffic	boolean	No	false

Truck

Field	Type	Required	Default
truck_id	string	Yes
truck_type	string	Yes
start_location	string	Yes
crew_size	integer	No	1
dims	Map[string, number]	No
dock_height_mode	string	No	"either"
has_dolly	boolean	No	false
has_liftgate	boolean	No	false
has_pallet_jack	boolean	No	false
hazmat_profile	Map[string, object]	No
loading_sides	List[string]	No
max_cargo_volume	number \| null	No
max_cargo_weight	number	No	34000.0
max_duration	integer	No	43200
max_miles	number	No	500.0
max_stops	integer	No	99
safety_profile	Map[string, object]	No
start_time	string	No	"08:00"
trailer_profile	string \| null	No
zones	Map[string, object]	No

Job

Field	Type	Required	Default
job_id	integer	Yes
exclusive_truck_ids	List[string] \| null	No
priority	integer	No	1
stops	List[Stop]	No

Stop

Field	Type	Required	Default
stop_id	string	Yes
type	string	Yes
lat	number	Yes
lng	number	Yes
access_restrictions	List[string]	No
address	string	No	""
dock_height	string \| null	No
earliest	string \| null	No
items	List[Item]	No
latest	string \| null	No
loading_side	string \| null	No
pickup_delivery_id	string \| null	No
requires_dolly	boolean \| null	No
requires_liftgate	boolean \| null	No
requires_pallet_jack	boolean \| null	No
safety_tags	List[string]	No
service_time_sec	integer \| null	No

Item

Field	Type	Required	Default
item_id	string	Yes
allowed_orientations	List[string]	No
assembly_id	string \| null	No
can_accept_underload	boolean	No	false
can_nest_with	List[string]	No
constraints	Map[string, object] \| null	No
dims	Dimensions	No
fragile	boolean	No	false
hazmat	Map[string, object] \| null	No
is_nestable	boolean	No	false
is_top_flat	boolean	No	true
item_class	string	No	"generic"
job_id	integer \| null	No
max_stack_weight	number	No	99999.0
max_tier	integer	No	10
mesh_format	string \| null	No
mesh_url	string \| null	No
position_constraint	string	No	"none"
stack_group_id	string \| null	No
stack_members	List[string] \| null	No
stackable	boolean	No	true
stop_id	string \| null	No
stop_seq_index	integer \| null	No
strap_required	boolean	No	false
temperature_zone	string \| null	No
tilt_modes	List[string]	No
volume	number	No	0.0
weight	number	No	0.0

Dimensions

Field	Type	Required
h	number	No
l	number	No
w	number	No

ScenarioSpec

Field	Type	Required	Description
scenario_id	string	Yes	Stable scenario identifier (client-provided).
jsonpatch	List[Map[string, object]] \| null	No	RFC 6902 JSON Patch operations to apply to the full payload for this scenario.
label	string \| null	No	Human label for display.
objective	object \| null	No	Objective override for this scenario.
objective_name	string \| null	No	Objective name override (alias).
policies_patch	Map[string, object] \| null	No	Deep-merge patch to apply to config.policies for this scenario (overrides baseline).

Examples

Optimize (minimal)

{
  "config": {
    "api_key": "test_api_key_123",
    "depot_address": "350 5th Ave, New York, NY 10118",
    "depot_lat": 40.7484,
    "depot_lng": -73.9857
  },
  "trucks": [
    {
      "truck_id": "T26-001",
      "truck_type": "box-26",
      "start_location": "350 5th Ave, New York, NY 10118",
      "start_time": "08:00"
    }
  ],
  "jobs": [
    {
      "job_id": 1,
      "priority": 1,
      "stops": [
        {
          "stop_id": "S1",
          "type": "delivery",
          "address": "11 Wall St, New York, NY 10005",
          "lat": 40.7074,
          "lng": -74.0113,
          "items": []
        }
      ]
    }
  ]
}

Optimize (full — all params)

{
  "config": {
    "api_key": "test_api_key_123",
    "depot_address": "350 5th Ave, New York, NY 10118",
    "depot_lat": 40.7484,
    "depot_lng": -73.9857,
    "travel_mode": "driving",
    "unit_system": "imperial",
    "timezone": "America/New_York",
    "objective_name": "minimize_miles",
    "objective": {
      "truck_fixed_cost_miles": 60.0,
      "weights": {
        "total_miles": 1.0,
        "trucks_used": 8.0,
        "unplaced_items": 250.0,
        "weight_distribution_penalty": 3.0,
        "fragile_violation_penalty": 6.0
      }
    },
    "travel_matrix": {
      "provider": "haversine",
      "osrm_base_url": "https://router.project-osrm.org",
      "osrm_profile": "driving",
      "traffic": true,
      "departure_time": "2026-01-02T08:00:00-05:00",
      "routing_preference": "TRAFFIC_AWARE",
      "timeout_sec": 12.0,
      "fallback_to_haversine": true,
      "max_elements_per_request": 625,
      "cache_ttl_sec": 7200,
      "cache_max_entries": 50000
    },
    "google_api_key": "TEST_GOOGLE_KEY",
    "seed": 12345,
    "webhook_url": "https://example.com/webhook",
    "async_stop_threshold": 10,
    "two_man_lift_enabled": true,
    "two_man_lift_threshold_lbs": 100.0,
    "break_rules": {
      "mandatory_break_duration": 1800,
      "drive_time_before_break": 10800
    },
    "enforce_geometry": true,
    "priority_mode": "hard",
    "lifo_mode": "hard",
    "securement_checks_enabled": true,
    "securement_default_strap_wll_lbs": 2500.0,
    "time_window_mode": "soft",
    "soft_tw_penalty_per_minute": 10,
    "policies": {
      "rear_load_bias": true,
      "center_balance_mode": true,
      "spread_items": true,
      "aisle_priority": true,
      "strap_priority": true,
      "fragile_separation": true,
      "enable_voxel_nesting": true,
      "voxel_pitch_in": 2.0,
      "objective_name": "minimize_miles",
      "objective": {
        "name": "minimize_miles",
        "truck_fixed_cost_miles": 60.0,
        "weights": {
          "total_miles": 1.0,
          "trucks_used": 8.0,
          "unplaced_items": 250.0
        }
      }
    },
    "auto_tuning": true,
    "max_auto_passes": 2,
    "debug": true,
    "metaheuristic": {
      "enable_ga": true,
      "population_size": 12,
      "generations": 6,
      "elite_fraction": 0.25,
      "mutation_rate": 0.35
    },
    "quality_weights": {
      "routing_weight": 0.55,
      "loading_weight": 0.45
    },
    "include_feasibility_explanations": true,
    "include_actionable_recommendations": true
  },
  "trucks": [
    {
      "truck_id": "T26-001",
      "truck_type": "box-26",
      "start_location": "350 5th Ave, New York, NY 10118",
      "start_time": "08:00",
      "crew_size": 2,
      "dims": {
        "l": 312.0,
        "w": 96.0,
        "h": 96.0
      },
      "max_miles": 180.0,
      "max_duration": 36000,
      "max_stops": 30,
      "max_cargo_weight": 12000.0,
      "max_cargo_volume": 1400.0,
      "trailer_profile": "box-26",
      "has_liftgate": true,
      "has_pallet_jack": true,
      "has_dolly": true,
      "dock_height_mode": "either",
      "loading_sides": [
        "rear",
        "side"
      ],
      "safety_profile": {
        "max_vehicle_length_ft": 26,
        "max_height_ft": 12.5,
        "allowed_tags": [
          "highway",
          "arterial",
          "industrial",
          "residential"
        ],
        "prohibited_access_flags": [
          "no_26ft"
        ],
        "prohibited_road_tags_for_hazmat": [
          "tunnel",
          "bridge_restricted"
        ],
        "oversize_thresholds": {
          "max_single_piece_weight_lbs": 2500.0,
          "max_single_piece_length_in": 192.0,
          "max_single_piece_width_in": 96.0,
          "max_single_piece_height_in": 84.0,
          "near_limit_pct": 0.92,
          "permit_weight_lbs": 5000.0,
          "permit_length_in": 240.0,
          "permit_width_in": 102.0,
          "permit_height_in": 96.0
        }
      },
      "hazmat_profile": {
        "enabled": true,
        "allowed_classes": [
          "3",
          "8"
        ],
        "max_hazmat_weight": 600.0
      },
      "zones": {
        "temperature": "ambient"
      }
    },
    {
      "truck_id": "T53-001",
      "truck_type": "dry-van-53",
      "start_location": "350 5th Ave, New York, NY 10118",
      "start_time": "07:30",
      "crew_size": 1,
      "dims": {
        "l": 636.0,
        "w": 100.0,
        "h": 110.0
      },
      "max_miles": 450.0,
      "max_duration": 43200,
      "max_stops": 60,
      "max_cargo_weight": 34000.0,
      "max_cargo_volume": null,
      "trailer_profile": "dry-van-53",
      "has_liftgate": false,
      "has_pallet_jack": false,
      "has_dolly": false,
      "dock_height_mode": "dock",
      "loading_sides": [
        "rear"
      ],
      "safety_profile": {
        "max_vehicle_length_ft": 53,
        "max_height_ft": 13.5,
        "allowed_tags": [
          "highway",
          "arterial",
          "industrial"
        ],
        "prohibited_access_flags": [
          "no_53ft"
        ],
        "prohibited_road_tags_for_hazmat": [
          "tunnel",
          "bridge_restricted"
        ],
        "oversize_thresholds": {
          "max_single_piece_weight_lbs": 4000.0,
          "max_single_piece_length_in": 240.0,
          "max_single_piece_width_in": 96.0,
          "max_single_piece_height_in": 96.0,
          "near_limit_pct": 0.92,
          "permit_weight_lbs": 8000.0,
          "permit_length_in": 360.0,
          "permit_width_in": 102.0,
          "permit_height_in": 108.0
        }
      },
      "hazmat_profile": {
        "enabled": false,
        "allowed_classes": [],
        "max_hazmat_weight": 1000.0
      },
      "zones": {
        "temperature": "ambient"
      }
    }
  ],
  "jobs": [
    {
      "job_id": 101,
      "priority": 2,
      "stops": [
        {
          "stop_id": "S-101-P1",
          "type": "pickup",
          "address": "1 Liberty Island, New York, NY 10004",
          "lat": 40.6892,
          "lng": -74.0445,
          "earliest": "2026-01-02T08:30:00-05:00",
          "latest": "2026-01-02T10:30:00-05:00",
          "service_time_sec": 900,
          "items": [],
          "pickup_delivery_id": "PD-101",
          "safety_tags": [
            "industrial"
          ],
          "access_restrictions": [],
          "requires_liftgate": null,
          "requires_pallet_jack": null,
          "requires_dolly": null,
          "dock_height": "ground",
          "loading_side": "rear"
        },
        {
          "stop_id": "S-101-D1",
          "type": "delivery",
          "address": "200 Central Park West, New York, NY 10024",
          "lat": 40.7813,
          "lng": -73.9735,
          "earliest": "2026-01-02T11:00:00-05:00",
          "latest": "2026-01-02T14:30:00-05:00",
          "service_time_sec": 1200,
          "items": [
            {
              "item_id": "SOFA-3SEAT-001",
              "weight": 180.0,
              "volume": 90.0,
              "dims": {
                "l": 84.0,
                "w": 38.0,
                "h": 34.0
              },
              "item_class": "upholstery",
              "stackable": false,
              "is_top_flat": false,
              "fragile": false,
              "max_stack_weight": 0.0,
              "max_tier": 1,
              "position_constraint": "bottom",
              "allowed_orientations": [
                "upright"
              ],
              "tilt_modes": [
                "upright"
              ],
              "strap_required": true,
              "assembly_id": "LIVING-SET-A",
              "mesh_url": null,
              "mesh_format": null,
              "can_accept_underload": false,
              "is_nestable": false,
              "can_nest_with": [],
              "job_id": 101,
              "stop_id": "S-101-D1",
              "stop_seq_index": 1,
              "stack_group_id": null,
              "stack_members": null,
              "hazmat": {
                "enabled": false,
                "class": null,
                "un_number": null,
                "packing_group": null,
                "incompatible_with": [],
                "requires_separation_in": 6.0
              },
              "constraints": {
                "bottom_layer": true,
                "top_layer": false,
                "front_load": false,
                "rear_load": true,
                "z_band": "bottom"
              },
              "temperature_zone": "ambient"
            },
            {
              "item_id": "TABLE-GLASS-002",
              "weight": 120.0,
              "volume": 40.0,
              "dims": {
                "l": 60.0,
                "w": 36.0,
                "h": 30.0
              },
              "item_class": "glass",
              "stackable": false,
              "is_top_flat": true,
              "fragile": true,
              "max_stack_weight": 0.0,
              "max_tier": 1,
              "position_constraint": "rear",
              "allowed_orientations": [
                "upright",
                "rotated"
              ],
              "tilt_modes": [
                "upright",
                "side"
              ],
              "strap_required": true,
              "assembly_id": null,
              "mesh_url": null,
              "mesh_format": null,
              "can_accept_underload": false,
              "is_nestable": false,
              "can_nest_with": [],
              "job_id": 101,
              "stop_id": "S-101-D1",
              "stop_seq_index": 1,
              "stack_group_id": null,
              "stack_members": null,
              "hazmat": {
                "enabled": false,
                "class": null,
                "un_number": null,
                "packing_group": null,
                "incompatible_with": [],
                "requires_separation_in": 6.0
              },
              "constraints": {
                "bottom_layer": false,
                "top_layer": true,
                "front_load": false,
                "rear_load": false,
                "z_band": "top"
              },
              "temperature_zone": "ambient"
            }
          ],
          "pickup_delivery_id": "PD-101",
          "safety_tags": [
            "residential"
          ],
          "access_restrictions": [
            "no_53ft"
          ],
          "requires_liftgate": true,
          "requires_pallet_jack": false,
          "requires_dolly": true,
          "dock_height": "ground",
          "loading_side": "either"
        }
      ],
      "exclusive_truck_ids": [
        "T26-001"
      ]
    },
    {
      "job_id": 202,
      "priority": 1,
      "stops": [
        {
          "stop_id": "S-202-D1",
          "type": "delivery",
          "address": "10 Exchange Pl, Jersey City, NJ 07302",
          "lat": 40.7163,
          "lng": -74.0334,
          "earliest": "2026-01-02T09:00:00-05:00",
          "latest": "2026-01-02T12:00:00-05:00",
          "service_time_sec": 600,
          "items": [
            {
              "item_id": "PAINT-5GAL-UN1263",
              "weight": 55.0,
              "volume": 2.0,
              "dims": {
                "l": 14.0,
                "w": 14.0,
                "h": 18.0
              },
              "item_class": "hazmat",
              "stackable": true,
              "is_top_flat": true,
              "fragile": false,
              "max_stack_weight": 500.0,
              "max_tier": 4,
              "position_constraint": "none",
              "allowed_orientations": [
                "upright",
                "rotated"
              ],
              "tilt_modes": [
                "upright"
              ],
              "strap_required": false,
              "assembly_id": null,
              "mesh_url": null,
              "mesh_format": null,
              "can_accept_underload": true,
              "is_nestable": true,
              "can_nest_with": [
                "hazmat",
                "generic"
              ],
              "job_id": 202,
              "stop_id": "S-202-D1",
              "stop_seq_index": 0,
              "stack_group_id": "STACK-PAINT-1",
              "stack_members": [
                "PAINT-5GAL-UN1263"
              ],
              "hazmat": {
                "enabled": true,
                "class": "3",
                "un_number": "UN1263",
                "packing_group": "II",
                "incompatible_with": [
                  "5.1"
                ],
                "requires_separation_in": 12.0
              },
              "constraints": {
                "bottom_layer": true,
                "top_layer": false,
                "front_load": true,
                "rear_load": false,
                "z_band": null
              },
              "temperature_zone": "ambient"
            }
          ],
          "pickup_delivery_id": null,
          "safety_tags": [
            "industrial"
          ],
          "access_restrictions": [],
          "requires_liftgate": false,
          "requires_pallet_jack": true,
          "requires_dolly": false,
          "dock_height": "dock",
          "loading_side": "rear"
        }
      ],
      "exclusive_truck_ids": null
    }
  ]
}

Optimize scenarios

{
  "base_request": {
    "config": {
      "api_key": "test_api_key_123",
      "depot_address": "350 5th Ave, New York, NY 10118",
      "depot_lat": 40.7484,
      "depot_lng": -73.9857,
      "travel_mode": "driving",
      "unit_system": "imperial",
      "timezone": "America/New_York",
      "objective_name": "minimize_miles",
      "objective": {
        "truck_fixed_cost_miles": 60.0,
        "weights": {
          "total_miles": 1.0,
          "trucks_used": 8.0,
          "unplaced_items": 250.0,
          "weight_distribution_penalty": 3.0,
          "fragile_violation_penalty": 6.0
        }
      },
      "travel_matrix": {
        "provider": "haversine",
        "osrm_base_url": "https://router.project-osrm.org",
        "osrm_profile": "driving",
        "traffic": true,
        "departure_time": "2026-01-02T08:00:00-05:00",
        "routing_preference": "TRAFFIC_AWARE",
        "timeout_sec": 12.0,
        "fallback_to_haversine": true,
        "max_elements_per_request": 625,
        "cache_ttl_sec": 7200,
        "cache_max_entries": 50000
      },
      "google_api_key": "TEST_GOOGLE_KEY",
      "seed": 12345,
      "webhook_url": "https://example.com/webhook",
      "async_stop_threshold": 10,
      "two_man_lift_enabled": true,
      "two_man_lift_threshold_lbs": 100.0,
      "break_rules": {
        "mandatory_break_duration": 1800,
        "drive_time_before_break": 10800
      },
      "enforce_geometry": true,
      "priority_mode": "hard",
      "lifo_mode": "hard",
      "securement_checks_enabled": true,
      "securement_default_strap_wll_lbs": 2500.0,
      "time_window_mode": "soft",
      "soft_tw_penalty_per_minute": 10,
      "policies": {
        "rear_load_bias": true,
        "center_balance_mode": true,
        "spread_items": true,
        "aisle_priority": true,
        "strap_priority": true,
        "fragile_separation": true,
        "enable_voxel_nesting": true,
        "voxel_pitch_in": 2.0,
        "objective_name": "minimize_miles",
        "objective": {
          "name": "minimize_miles",
          "truck_fixed_cost_miles": 60.0,
          "weights": {
            "total_miles": 1.0,
            "trucks_used": 8.0,
            "unplaced_items": 250.0
          }
        }
      },
      "auto_tuning": true,
      "max_auto_passes": 2,
      "debug": true,
      "metaheuristic": {
        "enable_ga": true,
        "population_size": 12,
        "generations": 6,
        "elite_fraction": 0.25,
        "mutation_rate": 0.35
      },
      "quality_weights": {
        "routing_weight": 0.55,
        "loading_weight": 0.45
      },
      "include_feasibility_explanations": true,
      "include_actionable_recommendations": true
    },
    "vehicles": [
      {
        "truck_id": "T26-001",
        "truck_type": "box-26",
        "start_location": "350 5th Ave, New York, NY 10118",
        "start_time": "08:00",
        "crew_size": 2,
        "dims": {
          "l": 312.0,
          "w": 96.0,
          "h": 96.0
        },
        "max_miles": 180.0,
        "max_duration": 36000,
        "max_stops": 30,
        "max_cargo_weight": 12000.0,
        "max_cargo_volume": 1400.0,
        "trailer_profile": "box-26",
        "has_liftgate": true,
        "has_pallet_jack": true,
        "has_dolly": true,
        "dock_height_mode": "either",
        "loading_sides": [
          "rear",
          "side"
        ],
        "safety_profile": {
          "max_vehicle_length_ft": 26,
          "max_height_ft": 12.5,
          "allowed_tags": [
            "highway",
            "arterial",
            "industrial",
            "residential"
          ],
          "prohibited_access_flags": [
            "no_26ft"
          ],
          "prohibited_road_tags_for_hazmat": [
            "tunnel",
            "bridge_restricted"
          ],
          "oversize_thresholds": {
            "max_single_piece_weight_lbs": 2500.0,
            "max_single_piece_length_in": 192.0,
            "max_single_piece_width_in": 96.0,
            "max_single_piece_height_in": 84.0,
            "near_limit_pct": 0.92,
            "permit_weight_lbs": 5000.0,
            "permit_length_in": 240.0,
            "permit_width_in": 102.0,
            "permit_height_in": 96.0
          }
        },
        "hazmat_profile": {
          "enabled": true,
          "allowed_classes": [
            "3",
            "8"
          ],
          "max_hazmat_weight": 600.0
        },
        "zones": {
          "temperature": "ambient"
        }
      },
      {
        "truck_id": "T53-001",
        "truck_type": "dry-van-53",
        "start_location": "350 5th Ave, New York, NY 10118",
        "start_time": "07:30",
        "crew_size": 1,
        "dims": {
          "l": 636.0,
          "w": 100.0,
          "h": 110.0
        },
        "max_miles": 450.0,
        "max_duration": 43200,
        "max_stops": 60,
        "max_cargo_weight": 34000.0,
        "max_cargo_volume": null,
        "trailer_profile": "dry-van-53",
        "has_liftgate": false,
        "has_pallet_jack": false,
        "has_dolly": false,
        "dock_height_mode": "dock",
        "loading_sides": [
          "rear"
        ],
        "safety_profile": {
          "max_vehicle_length_ft": 53,
          "max_height_ft": 13.5,
          "allowed_tags": [
            "highway",
            "arterial",
            "industrial"
          ],
          "prohibited_access_flags": [
            "no_53ft"
          ],
          "prohibited_road_tags_for_hazmat": [
            "tunnel",
            "bridge_restricted"
          ],
          "oversize_thresholds": {
            "max_single_piece_weight_lbs": 4000.0,
            "max_single_piece_length_in": 240.0,
            "max_single_piece_width_in": 96.0,
            "max_single_piece_height_in": 96.0,
            "near_limit_pct": 0.92,
            "permit_weight_lbs": 8000.0,
            "permit_length_in": 360.0,
            "permit_width_in": 102.0,
            "permit_height_in": 108.0
          }
        },
        "hazmat_profile": {
          "enabled": false,
          "allowed_classes": [],
          "max_hazmat_weight": 1000.0
        },
        "zones": {
          "temperature": "ambient"
        }
      }
    ],
    "orders": [
      {
        "job_id": 101,
        "priority": 2,
        "stops": [
          {
            "stop_id": "S-101-P1",
            "type": "pickup",
            "address": "1 Liberty Island, New York, NY 10004",
            "lat": 40.6892,
            "lng": -74.0445,
            "earliest": "2026-01-02T08:30:00-05:00",
            "latest": "2026-01-02T10:30:00-05:00",
            "service_time_sec": 900,
            "items": [],
            "pickup_delivery_id": "PD-101",
            "safety_tags": [
              "industrial"
            ],
            "access_restrictions": [],
            "requires_liftgate": null,
            "requires_pallet_jack": null,
            "requires_dolly": null,
            "dock_height": "ground",
            "loading_side": "rear"
          },
          {
            "stop_id": "S-101-D1",
            "type": "delivery",
            "address": "200 Central Park West, New York, NY 10024",
            "lat": 40.7813,
            "lng": -73.9735,
            "earliest": "2026-01-02T11:00:00-05:00",
            "latest": "2026-01-02T14:30:00-05:00",
            "service_time_sec": 1200,
            "items": [
              {
                "item_id": "SOFA-3SEAT-001",
                "weight": 180.0,
                "volume": 90.0,
                "dims": {
                  "l": 84.0,
                  "w": 38.0,
                  "h": 34.0
                },
                "item_class": "upholstery",
                "stackable": false,
                "is_top_flat": false,
                "fragile": false,
                "max_stack_weight": 0.0,
                "max_tier": 1,
                "position_constraint": "bottom",
                "allowed_orientations": [
                  "upright"
                ],
                "tilt_modes": [
                  "upright"
                ],
                "strap_required": true,
                "assembly_id": "LIVING-SET-A",
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": false,
                "is_nestable": false,
                "can_nest_with": [],
                "job_id": 101,
                "stop_id": "S-101-D1",
                "stop_seq_index": 1,
                "stack_group_id": null,
                "stack_members": null,
                "hazmat": {
                  "enabled": false,
                  "class": null,
                  "un_number": null,
                  "packing_group": null,
                  "incompatible_with": [],
                  "requires_separation_in": 6.0
                },
                "constraints": {
                  "bottom_layer": true,
                  "top_layer": false,
                  "front_load": false,
                  "rear_load": true,
                  "z_band": "bottom"
                },
                "temperature_zone": "ambient"
              },
              {
                "item_id": "TABLE-GLASS-002",
                "weight": 120.0,
                "volume": 40.0,
                "dims": {
                  "l": 60.0,
                  "w": 36.0,
                  "h": 30.0
                },
                "item_class": "glass",
                "stackable": false,
                "is_top_flat": true,
                "fragile": true,
                "max_stack_weight": 0.0,
                "max_tier": 1,
                "position_constraint": "rear",
                "allowed_orientations": [
                  "upright",
                  "rotated"
                ],
                "tilt_modes": [
                  "upright",
                  "side"
                ],
                "strap_required": true,
                "assembly_id": null,
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": false,
                "is_nestable": false,
                "can_nest_with": [],
                "job_id": 101,
                "stop_id": "S-101-D1",
                "stop_seq_index": 1,
                "stack_group_id": null,
                "stack_members": null,
                "hazmat": {
                  "enabled": false,
                  "class": null,
                  "un_number": null,
                  "packing_group": null,
                  "incompatible_with": [],
                  "requires_separation_in": 6.0
                },
                "constraints": {
                  "bottom_layer": false,
                  "top_layer": true,
                  "front_load": false,
                  "rear_load": false,
                  "z_band": "top"
                },
                "temperature_zone": "ambient"
              }
            ],
            "pickup_delivery_id": "PD-101",
            "safety_tags": [
              "residential"
            ],
            "access_restrictions": [
              "no_53ft"
            ],
            "requires_liftgate": true,
            "requires_pallet_jack": false,
            "requires_dolly": true,
            "dock_height": "ground",
            "loading_side": "either"
          }
        ],
        "exclusive_truck_ids": [
          "T26-001"
        ]
      },
      {
        "job_id": 202,
        "priority": 1,
        "stops": [
          {
            "stop_id": "S-202-D1",
            "type": "delivery",
            "address": "10 Exchange Pl, Jersey City, NJ 07302",
            "lat": 40.7163,
            "lng": -74.0334,
            "earliest": "2026-01-02T09:00:00-05:00",
            "latest": "2026-01-02T12:00:00-05:00",
            "service_time_sec": 600,
            "items": [
              {
                "item_id": "PAINT-5GAL-UN1263",
                "weight": 55.0,
                "volume": 2.0,
                "dims": {
                  "l": 14.0,
                  "w": 14.0,
                  "h": 18.0
                },
                "item_class": "hazmat",
                "stackable": true,
                "is_top_flat": true,
                "fragile": false,
                "max_stack_weight": 500.0,
                "max_tier": 4,
                "position_constraint": "none",
                "allowed_orientations": [
                  "upright",
                  "rotated"
                ],
                "tilt_modes": [
                  "upright"
                ],
                "strap_required": false,
                "assembly_id": null,
                "mesh_url": null,
                "mesh_format": null,
                "can_accept_underload": true,
                "is_nestable": true,
                "can_nest_with": [
                  "hazmat",
                  "generic"
                ],
                "job_id": 202,
                "stop_id": "S-202-D1",
                "stop_seq_index": 0,
                "stack_group_id": "STACK-PAINT-1",
                "stack_members": [
                  "PAINT-5GAL-UN1263"
                ],
                "hazmat": {
                  "enabled": true,
                  "class": "3",
                  "un_number": "UN1263",
                  "packing_group": "II",
                  "incompatible_with": [
                    "5.1"
                  ],
                  "requires_separation_in": 12.0
                },
                "constraints": {
                  "bottom_layer": true,
                  "top_layer": false,
                  "front_load": true,
                  "rear_load": false,
                  "z_band": null
                },
                "temperature_zone": "ambient"
              }
            ],
            "pickup_delivery_id": null,
            "safety_tags": [
              "industrial"
            ],
            "access_restrictions": [],
            "requires_liftgate": false,
            "requires_pallet_jack": true,
            "requires_dolly": false,
            "dock_height": "dock",
            "loading_side": "rear"
          }
        ],
        "exclusive_truck_ids": null
      }
    ]
  },
  "scenarios": [
    {
      "scenario_id": "S1_obj_min_trucks",
      "label": "Minimize trucks used",
      "objective_name": "minimize_trucks",
      "policies_patch": {
        "rear_load_bias": false,
        "center_balance_mode": true
      }
    },
    {
      "scenario_id": "S2_soft_tw_no_ga",
      "label": "Soft TW + GA off, reduce penalty",
      "policies_patch": {
        "objective_name": "maximize_items_placed",
        "fragile_separation": true
      },
      "jsonpatch": [
        {
          "op": "replace",
          "path": "/config/time_window_mode",
          "value": "soft"
        },
        {
          "op": "replace",
          "path": "/config/soft_tw_penalty_per_minute",
          "value": 2
        },
        {
          "op": "replace",
          "path": "/config/metaheuristic/enable_ga",
          "value": false
        },
        {
          "op": "replace",
          "path": "/trucks/0/max_miles",
          "value": 120.0
        }
      ]
    }
  ],
  "options": {
    "include_plans": true,
    "max_scenarios": 8
  }
}