--- title: "Create lot" method: POST path: "/lots" tags: ["lots"] --- # Create lot `POST /lots` ## Request - Base URL: `https://api.vepathos.com` - URL: `https://api.vepathos.com/lots` - Auth: API key in header `Authorization` Groups a depot, a fleet and deliveries for one optimization run, and reserves the lot's stops against your monthly allowance. Returns `403` with `reason` `max_stops_per_request`, `monthly_limit` or `max_stops_per_route` when the lot does not fit your plan. ## Request body - DeliveryLotCreate - `vehicle_limits` VehicleLimits - `volume_min` integer, nullable - `volume_max` integer, nullable - `capacity_min` integer, nullable - `capacity_max` integer, nullable - `route_limits` RouteLimits - `stops_min` integer, nullable - `stops_max` integer, nullable - `length_min` integer, nullable - `length_max` integer, nullable - `length_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` integer, nullable - `time_max` integer, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `milestone_id` string, required: Depot every route starts from. - `deliveries` string[], required: Delivery ids to plan. - `fleet_id` string, required: Fleet available for this run. - `drivers` string[], nullable: Driver ids attached to the lot. - `config` LotConfig: Per-run settings for a delivery lot. Every section is optional. - `vehicles` VehiclesConfig - `defaults` VehicleRunConfig - `capacity` VehicleCapacityConfig - `volume_max` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight_max` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `route` VehicleRouteConfig - `stops_min` integer, nullable - `stops_max` integer, nullable - `distance_min` number, nullable - `distance_max` number, nullable - `distance_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` number, nullable - `time_max` number, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `behavior` VehicleBehaviorConfig - `priority` integer, nullable: Dispatch priority. Higher values are used first when types are interchangeable. - `overflow_vehicle` boolean, nullable: Hold this type back until the primary types are full. - `overrides` VehicleOverride[], nullable: Per-vehicle settings that win over `defaults`. - `capacity` VehicleCapacityConfig - `volume_max` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight_max` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `route` VehicleRouteConfig - `stops_min` integer, nullable - `stops_max` integer, nullable - `distance_min` number, nullable - `distance_max` number, nullable - `distance_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` number, nullable - `time_max` number, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `behavior` VehicleBehaviorConfig - `priority` integer, nullable: Dispatch priority. Higher values are used first when types are interchangeable. - `overflow_vehicle` boolean, nullable: Hold this type back until the primary types are full. - `vehicle_id` string, required: Vehicle this override applies to. - `rebalance` RebalanceConfig - `rebalance_by_volume` RebalanceByVolumeConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_volume_capacity_ratio_vehicle_initial` number, nullable: Minimum volume fill ratio (0 to 1) during the first clustering pass. - `max_volume_capacity_ratio_vehicle_initial` number, nullable: Maximum volume fill ratio (0 to 1) during the first clustering pass. - `min_volume_capacity_ratio_vehicle` number, nullable: Minimum volume fill ratio (0 to 1) for final routes. - `max_volume_capacity_ratio_vehicle` number, nullable: Maximum volume fill ratio (0 to 1) for final routes. - `rebalance_by_size` RebalanceBySizeConfig - `enabled` boolean: Even out the number of stops per route. - `rebalance_by_weight` RebalanceByWeightConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_weight_capacity_ratio_vehicle` number, nullable: Minimum weight fill ratio (0 to 1). - `max_weight_capacity_ratio_vehicle` number, nullable: Maximum weight fill ratio (0 to 1). - `rebalance_by_time` RebalanceByTimeConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_time_minutes_per_route` number, nullable: Target minimum route duration in minutes. - `max_time_minutes_per_route` number, nullable: Target maximum route duration in minutes. - `rebalance_by_distance` RebalanceByDistanceConfig - `enabled` boolean: Even out the distance each vehicle drives. - `schedule` ScheduleConfig - `start_at` string, date-time, nullable: ISO 8601 date-time routes start, read in UTC. - `respect_delivery_windows` boolean, nullable: When `true`, stops with `schedules` are only placed where the arrival falls inside a window. - `time_windows` TimeWindowsConfig - `early_tolerance_min` number, nullable: Minutes a vehicle may arrive before a window opens. - `late_tolerance_min` number, nullable: Minutes a vehicle may arrive after a window closes. - `clustering` ClusteringConfig: Clustering options a run may set. Other clustering settings are managed by Vepathos. - `force_vehicles_fleet_match` boolean, nullable: `true` sizes routes so the plan uses the whole fleet as declared. `false` lets the planner build longer routes and leave vehicles unused when fewer are enough. When omitted, route sizes are derived from the fleet size. - `routing` RoutingConfig: Routing options a run may override. Other routing settings are managed by Vepathos and ignored if sent. - `service_time_min` number, nullable: Minutes spent at each stop. Used for arrival times and route durations. - `avg_speed_kph` number, nullable: Average travel speed in km/h used to estimate travel time. - `zone` string, nullable: Reserved grouping label. Leave unset unless Vepathos asks you to use it. ## Response `201` The created delivery lot. - DeliveryLotResponse - `vehicle_limits` VehicleLimits - `volume_min` integer, nullable - `volume_max` integer, nullable - `capacity_min` integer, nullable - `capacity_max` integer, nullable - `route_limits` RouteLimits - `stops_min` integer, nullable - `stops_max` integer, nullable - `length_min` integer, nullable - `length_max` integer, nullable - `length_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` integer, nullable - `time_max` integer, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `id` union, required - string - integer - `state` 'UNPROCESSED' | 'PROCESSING' | 'OPTIMIZING' | 'PROCESSED' | 'CANCELED', required - `milestone` MilestoneResponse, required - `name` string, required: Display name. - `location` string, required: Coordinates in ISO 6709 decimal degrees, latitude then longitude with signs, e.g. `+40.7128-74.0060`. - `category` 'DEPOT' | 'DISTRIBUTION_CENTER' | 'LOADING_POINT' | 'WAREHOUSE' | 'TRANSFER_POINT' - `id` union, required - string - integer - `deliveries` DeliveryResponse[], required: Delivery ids to plan. - `destination` string, required: Stop location. Coordinates in ISO 6709 decimal degrees, latitude then longitude with signs, e.g. `+40.7128-74.0060`. - `method` 'DELIVERY' | 'PICKUP' | 'SIGNATURE' - `schedules` string[], nullable: Time windows. RFC 5545 VEVENT: `DTSTART` plus `DTEND` or `DURATION`, optionally `RRULE`. Join lines with `\n`. - `width` integer, nullable: Package width, in `length_unit`. Integer. - `height` integer, nullable: Package height, in `length_unit`. Integer. - `depth` integer, nullable: Package depth, in `length_unit`. Integer. - `length_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `volume` integer, nullable: Package volume, in `volume_unit`. Integer. - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight` integer, nullable: Package weight, in `weight_unit`. Integer; use `GRAMS` for fractional kilograms. - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `packaging` 'BOX' | 'ENVELOPE' | 'BAG' | 'CARTON' | 'PALLET' | 'SHRINK_WRAP' - `handling` SpecialHandling[], nullable - `value_cents` integer, nullable: Declared value in minor units (`5000` is 50.00). - `value_currency` string, nullable: ISO 4217 currency code. - `extra` unknown - `id` union, required - string - integer - `milestone` MilestoneResponse, required - `name` string, required: Display name. - `location` string, required: Coordinates in ISO 6709 decimal degrees, latitude then longitude with signs, e.g. `+40.7128-74.0060`. - `category` 'DEPOT' | 'DISTRIBUTION_CENTER' | 'LOADING_POINT' | 'WAREHOUSE' | 'TRANSFER_POINT' - `id` union, required - string - integer - `arrival_time` union: Estimated arrival in minutes after midnight, including the route start from `config.schedule.start_at`. Present on deliveries inside plan routes. - number - string - `delivery_count` integer, nullable - `fleet` FleetResponse - `name` string, required - `vehicles` FleetVehicleResponse[], required - `name` string, required - `volume` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `consumption` integer, nullable - `consumption_unit` 'LITERS_PER_100KM' | 'KILOMETERS_PER_LITER' | 'MILES_PER_GALLON' | 'GALLONS_PER_MILE' - `category_type` 'TRUCK' | 'VAN' | 'PICKUP' | 'MOTORCYCLE' | 'BICYCLE' - `engine_type` 'GASOLINE' | 'DIESEL' | 'CNG' | 'ELECTRIC' | 'HYBRID' | 'MECHANIC' - `id` union, required - string - integer - `qty` integer, required - `alias` string, nullable: Name for this entry, unique within the fleet. Lets the same vehicle type appear more than once with different route or behavior limits. - `route` VehicleRouteConfig - `stops_min` integer, nullable - `stops_max` integer, nullable - `distance_min` number, nullable - `distance_max` number, nullable - `distance_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` number, nullable - `time_max` number, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `behavior` VehicleBehaviorConfig - `priority` integer, nullable: Dispatch priority. Higher values are used first when types are interchangeable. - `overflow_vehicle` boolean, nullable: Hold this type back until the primary types are full. - `id` union, required - string - integer - `drivers` DriverResponse[], nullable: Driver ids attached to the lot. - `first_name` string, required - `last_name` string, nullable - `work_schedules` string[], nullable: Working hours. RFC 5545 VEVENT: `DTSTART` plus `DTEND` or `DURATION`, optionally `RRULE`. Join lines with `\n`. - `start_point` string, nullable: Where the driver starts the day. Coordinates in ISO 6709 decimal degrees, latitude then longitude with signs, e.g. `+40.7128-74.0060`. - `end_point` string, nullable: Where the driver ends the day. Coordinates in ISO 6709 decimal degrees, latitude then longitude with signs, e.g. `+40.7128-74.0060`. - `work_areas` array[], nullable: Polygons, each an array of `geo_point` vertices. - string[] - `id` union, required - string - integer - `vehicles` DriverVehicleResponse[], nullable: Vehicle types the driver can operate. - `name` string, required - `volume` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `consumption` integer, nullable - `consumption_unit` 'LITERS_PER_100KM' | 'KILOMETERS_PER_LITER' | 'MILES_PER_GALLON' | 'GALLONS_PER_MILE' - `category_type` 'TRUCK' | 'VAN' | 'PICKUP' | 'MOTORCYCLE' | 'BICYCLE' - `engine_type` 'GASOLINE' | 'DIESEL' | 'CNG' | 'ELECTRIC' | 'HYBRID' | 'MECHANIC' - `id` union, required - string - integer - `qty` integer, required - `config` LotConfig: Per-run settings for a delivery lot. Every section is optional. - `vehicles` VehiclesConfig - `defaults` VehicleRunConfig - `capacity` VehicleCapacityConfig - `volume_max` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight_max` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `route` VehicleRouteConfig - `stops_min` integer, nullable - `stops_max` integer, nullable - `distance_min` number, nullable - `distance_max` number, nullable - `distance_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` number, nullable - `time_max` number, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `behavior` VehicleBehaviorConfig - `priority` integer, nullable: Dispatch priority. Higher values are used first when types are interchangeable. - `overflow_vehicle` boolean, nullable: Hold this type back until the primary types are full. - `overrides` VehicleOverride[], nullable: Per-vehicle settings that win over `defaults`. - `capacity` VehicleCapacityConfig - `volume_max` integer, nullable - `volume_unit` 'CUBIC_CENTIMETER' | 'CUBIC_METER' | 'LITER' | 'CUBIC_INCH' | 'CUBIC_FEET' | 'GALLON' - `weight_max` integer, nullable - `weight_unit` 'GRAMS' | 'KILOGRAMS' | 'OUNCES' | 'POUNDS' - `route` VehicleRouteConfig - `stops_min` integer, nullable - `stops_max` integer, nullable - `distance_min` number, nullable - `distance_max` number, nullable - `distance_unit` 'CENTIMETER' | 'METER' | 'KILOMETER' | 'INCH' | 'FEET' | 'MILE' - `time_min` number, nullable - `time_max` number, nullable - `time_unit` 'SECOND' | 'MINUTE' | 'HOUR' - `behavior` VehicleBehaviorConfig - `priority` integer, nullable: Dispatch priority. Higher values are used first when types are interchangeable. - `overflow_vehicle` boolean, nullable: Hold this type back until the primary types are full. - `vehicle_id` string, required: Vehicle this override applies to. - `rebalance` RebalanceConfig - `rebalance_by_volume` RebalanceByVolumeConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_volume_capacity_ratio_vehicle_initial` number, nullable: Minimum volume fill ratio (0 to 1) during the first clustering pass. - `max_volume_capacity_ratio_vehicle_initial` number, nullable: Maximum volume fill ratio (0 to 1) during the first clustering pass. - `min_volume_capacity_ratio_vehicle` number, nullable: Minimum volume fill ratio (0 to 1) for final routes. - `max_volume_capacity_ratio_vehicle` number, nullable: Maximum volume fill ratio (0 to 1) for final routes. - `rebalance_by_size` RebalanceBySizeConfig - `enabled` boolean: Even out the number of stops per route. - `rebalance_by_weight` RebalanceByWeightConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_weight_capacity_ratio_vehicle` number, nullable: Minimum weight fill ratio (0 to 1). - `max_weight_capacity_ratio_vehicle` number, nullable: Maximum weight fill ratio (0 to 1). - `rebalance_by_time` RebalanceByTimeConfig - `enabled` boolean: Apply this strategy. Defaults to `true` when the object is present. - `min_time_minutes_per_route` number, nullable: Target minimum route duration in minutes. - `max_time_minutes_per_route` number, nullable: Target maximum route duration in minutes. - `rebalance_by_distance` RebalanceByDistanceConfig - `enabled` boolean: Even out the distance each vehicle drives. - `schedule` ScheduleConfig - `start_at` string, date-time, nullable: ISO 8601 date-time routes start, read in UTC. - `respect_delivery_windows` boolean, nullable: When `true`, stops with `schedules` are only placed where the arrival falls inside a window. - `time_windows` TimeWindowsConfig - `early_tolerance_min` number, nullable: Minutes a vehicle may arrive before a window opens. - `late_tolerance_min` number, nullable: Minutes a vehicle may arrive after a window closes. - `clustering` ClusteringConfig: Clustering options a run may set. Other clustering settings are managed by Vepathos. - `force_vehicles_fleet_match` boolean, nullable: `true` sizes routes so the plan uses the whole fleet as declared. `false` lets the planner build longer routes and leave vehicles unused when fewer are enough. When omitted, route sizes are derived from the fleet size. - `routing` RoutingConfig: Routing options a run may override. Other routing settings are managed by Vepathos and ignored if sent. - `service_time_min` number, nullable: Minutes spent at each stop. Used for arrival times and route durations. - `avg_speed_kph` number, nullable: Average travel speed in km/h used to estimate travel time. - `zone` string, nullable: Reserved grouping label. Leave unset unless Vepathos asks you to use it. ## Other responses - `401`: Missing, expired or invalid access token. - `403`: A plan quota or optimization option blocks the request. `reason` names the limit. Nothing is reserved or charged. - `422`: The body or a parameter does not match the schema. --- [API](https://skmtc.dev/vepathos/apis/vepathos-route-optimization-api.md) · [All operations](https://skmtc.dev/vepathos/apis/vepathos-route-optimization-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vepathos/apis/vepathos-route-optimization-api/revisions/00caa1ca62d9?raw)