Schemas

SolveRequest

The complete request payload for the /problem endpoint.

userId

string · required

The User ID

ProblemRequest · required

The Problem object embedded within the main solve request.

exampleSlug

string

Optional. The slug of the published example scenario this solve was loaded from (as returned by /list_examples). Published examples legitimately exceed the free tier's size limits, so sending this grants a bounded allowance sized from that example's own row counts plus a small edit margin - enough to run and tweak the demo, and never more than the named example's real size. Omit it for a user's own scenarios; an unrecognised slug is ignored.

ProblemRequest

The Problem object embedded within the main solve request.

problemType

string · enum · required

Enum values:

pickup-delivery

vehicle-routing

Example: vehicle-routing

ProblemData · required

This schema defines the problem data for an optimization Problem. The particular data objects used will depend on the problemType.

TimeSettings

This schema defines how to interpet the input time field settings. Optimiciti allows for input times to be specified as absolute numeric values (i.e 0, 12, 60, etc.) or as date/time values (i.e. 1/1/2024, 2:24pm).

coordinateSystem

CoordinateSystem · enum

Which coordinate family this problem's locations use. geographic (the default, and what every existing payload means) uses latitude/longitude on the Earth. cartesian uses unbounded x/y on an arbitrary plane, for scenarios with positions but no addresses. It describes the DATA, not the costing, so it is set once per request rather than per cost setting - and it decides which distance/duration methods are valid.

Enum values:

geographic

cartesian

Default: geographic

StandardResponse

A standardized response envelope used across the API.

success

boolean

Indicates if the request was successful

Default: true

data

The main response payload. Can be an object, array, boolean, or string.

ResponseError

code

string · required

Internal error code

message

string · required

Human readable error message

details

object | null

Additional error context

AddressRequest

lat

number · min: -90 · max: 90 · required

Latitude of the location

lng

number · min: -180 · max: 180 · required

Longitude of the location

zoom

number

Zoom level for reverse geocoding

Default: 8

AddressResponse

address

string · required

BugReportRequest

user_email

string · email

Default:

bug_message

string

Default:

bug_files

string | null

bug_filenames

string[]

Default: []

CanUserSaveRequest

user_id

string · required

The User ID (Auth0 or internal)

ContactFormRequest

message

string · required

name

string

Default:

email

string · email

Default:

JobApplicationRequest

full_name

string · required

Applicant's full name

email

string · email · required

Applicant's email address

resume_file

string · required

Base64-encoded contents of the resume file

resume_filename

string · required

Original resume filename, used to derive the file extension

cover_letter

string

Optional cover letter message

Default:

RenameScenarioRequest

instance_id

string · required

new_name

string · required

RunIdRequest

run_id

string · required

The unique Run ID

RunItem

run_id

string · required

run_datetime_unix

integer · required

SampleTableRequest

tableName

string · required

Name of the table definition

columns

array | null

num_rows

integer

Number of sample rows to generate

Default: 5

SampleTableWrapper

SampleTableRequest · required

SaveCheckResponse

can_save

boolean · required

Whether the user is allowed to save more scenarios

remaining

number | null · required

Number of saves remaining; null when the plan is unlimited

SaveScenarioRequest

user_id

string · required

instance_id

string · required

input_object

object · required

instance_name

string

Default:

overwrite

boolean

Whether an existing scenario with this instance_id may be replaced. When false (the default), saving onto an existing instance_id fails with 409 SCENARIO_ALREADY_EXISTS instead of silently replacing the stored scenario.

Default: false

ScenarioRequest

scenarioId

string | null

The unique Scenario ID

scenarioName

string | null

Optional name to lookup example scenarios

SubscribeRequest

email

string · email · required

name

string

Default:

source

string

Default:

message

string

Default:

organization

string

Default:

TableExportRequest

tableArray

string · required

CSV string representation of the table

UpdateRunRequest

run_id

string · required

run_name

string · required

UpdateScenarioRequest

instance_id

string · required

new_name

string · required

state

object · required

UserHistoryRequest

user_id

string · required

The unique User ID

UserRunsResponse

RunItem[] · required

ProblemData

This schema defines the problem data for an optimization Problem. The particular data objects used will depend on the problemType.

Location[]

Trip[]

Vehicle[]

VehicleType[]

TravelCost[]

TimeSettings

timeUnit

string · enum

The time unit to use for optimization. This time unit will apply, as applicable, to location open and close windows, trip open and close windows, vehicle operating times, and travel durations. Integer (default) indicates that all times are in absolute time units from an arbitrarily defined time 0. Clock indicates that times will be interpreted as literal clock times and calendar dates.

Enum values:

integer

clock

Default: integer

timeFormat

string

The format to expect all time fields in. This field is only relevant when timeUnit = "clock". Formattings should match the formats described by the python pandas.Period.strftime class. For example, if the format used matches 09:32pm, then '%I:%M%p'. If null is passed, then the pandas.to_datetime function will be used to detect the format.

Example: I:%M%p

Default: null

multipleDays

A boolean field indicating whether to allow the optimization time period to extend multiple days. This field is relevant only when timeUnit = "datetime".

Default: false

dateUnit

string · enum

The date unit to use for optimization. This field is only relevant when timeUnit = "clock" and multipleDays = true. If this field is integer, then days will be measured as absolute days from an arbitrarily defined day 0. Calendar indidates that dates will be interpreted as literal calendar dates.

Enum values:

integer

calendar

Default: integer

dateFormat

string

The format to expect all dates fields in. This field is only relevant when dateUnit = "calendar", multipleDays = true, and timeUnit = "clock". Formattings should match the formats described by the python pandas.Period.strftime class. For example, if the format used matches 2024-12-31, then '%Y-%m-%d' should be passed for this parameter. If null is passed, then the pandas.to_datetime function will be used to detect the format.

Example: %Y-%m-%d

Default: null

Location

locationId

string · required

A string that uniquely identifies this location.

Example: 550e8400-e29b-41d4-a716-446655440000

locationName

string · required

A name for this location (optional).

Example: Chicago

demand

integer · min: 0

The amount of vehicle capacity this location consumes

Example: 10

Default: 1

latitude

number · float · min: -90 · max: 90

The latitude for this location. Required only if autoCalculateDuration or autoCalculateDistance is true.

Example: 39.791

longitude

number · float · min: -180 · max: 180

The longitude for this location. Required only if autoCalculateDuration or autoCalculateDistance is true.

Example: -86.148003

x

number | null

Cartesian x position on an arbitrary plane (warehouse floor, factory layout, PCB). Unbounded - deliberately NOT range-validated, unlike longitude. Use with coordinateSystem=cartesian; x is the exact counterpart of longitude (x = longitude, y = latitude), so a scenario can migrate between the two families without reordering. Supply either latitude/longitude or x/y, never both.

Example: 1250.5

y

number | null

Cartesian y position on an arbitrary plane. Unbounded - deliberately NOT range-validated, unlike latitude. Use with coordinateSystem=cartesian; y is the exact counterpart of latitude. Supply either latitude/longitude or x/y, never both.

Example: 880.25

isDepot

boolean

Whether this location serves only as a depot for vehicles (true) or if this location should be serviced.

Default: false

serviceDuration

number · float · min: 0

How long service at this location takes.

Example: 15.5

Default: 0

minArrivalTimeInt

integer | null · min: 0

An integer value representing the earliest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup.

Example: 10

Default: null

minArrivalTimeStr

string | null

A string value representing the earliest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 12:00:00am

Default: null

minArrivalDayInt

integer | null · min: 0

An integer value representing the earliest day this location can be serviced. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup.

Example: 1

Default: null

maxArrivalTimeInt

integer | null · min: 0

An integer value representing the latest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup.

Example: 100

Default: null

maxArrivalTimeStr

string | null

A string value representing the latest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 11:59:59pm

Default: null

maxArrivalDayInt

integer | null · min: 0

An integer value representing the latest day this location can be serviced. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup.

Example: 1

Default: null

exactArrivalTimeInt

integer | null · min: 0

An integer value representing the exact time this location must be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. A location may set EITHER the exact* fields OR the min*/max* window fields, never both — combining them returns 400 EXACT_ARRIVAL_CONFLICT. A pin no vehicle can reach returns 400 EXACT_ARRIVAL_INFEASIBLE naming the earliest feasible arrival; a pin that is reachable but unsatisfiable with the rest of the problem fails the run with 422 EXACT_ARRIVAL_UNSERVABLE rather than silently dropping the stop.

Example: 50

Default: null

exactArrivalTimeStr

string | null

A string value representing the exact time this location must be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings. This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. A location may set EITHER the exact* fields OR the min*/max* window fields, never both — combining them returns 400 EXACT_ARRIVAL_CONFLICT. A pin no vehicle can reach returns 400 EXACT_ARRIVAL_INFEASIBLE naming the earliest feasible arrival; a pin that is reachable but unsatisfiable with the rest of the problem fails the run with 422 EXACT_ARRIVAL_UNSERVABLE rather than silently dropping the stop.

Example: 2024-01-01 01:00:00am

Default: null

exactArrivalDayInt

integer | null · min: 0

An integer value representing the exact day this location must be serviced. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup. This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. A location may set EITHER the exact* fields OR the min*/max* window fields, never both — combining them returns 400 EXACT_ARRIVAL_CONFLICT. A pin no vehicle can reach returns 400 EXACT_ARRIVAL_INFEASIBLE naming the earliest feasible arrival; a pin that is reachable but unsatisfiable with the rest of the problem fails the run with 422 EXACT_ARRIVAL_UNSERVABLE rather than silently dropping the stop.

Example: 1

Default: null

color

string

The color to use for this location in the output. Accepts a hex code ("#FF0000") or a CSS color name ("crimson").

Example: #FF0000

vehicleTypeIds

array | null

The vehicleTypeIds that can service this location. These vehicleTypeIds must exist in the VehicleTypes passed in ProblemData for this problem. Leave empty if there are no restrictions on which vehicle types can service this location.

Example: {"0":"550e8400-e29b-41d4-a716-446655440000","1":"550e8400-e29b-41d4-a716-446655440001"}

fixedVehicleId

string | null

Optional. Pin this location to a specific vehicle: the solve must use this vehicle to serve this stop. The vehicleId must exist in the Vehicles passed in ProblemData. If the pin cannot be satisfied - the vehicle does not exist, or its type is excluded by this location's vehicleTypeIds - the location is returned unassigned rather than served by a different vehicle. Leave null for no pin.

Example: 550e8400-e29b-41d4-a716-446655440000

Trip

tripId

string · required

A unique identifier for this trip.

Example: 550e8400-e29b-41d4-a716-446655440000

fromLocationId

string · required

The locationId for the origin location of this trip. This locationId must exist in the Locations passed in ProblemData for this problem.

Example: 550e8400-e29b-41d4-a716-446655440000

toLocationId

string · required

The locationId for the destination location of this trip. This locationId must exist in the Locations passed in ProblemData for this problem.

Example: 550e8400-e29b-41d4-a716-446655440001

tripName

string

A name for this trip (optional).

Example: Trip 1

vehicleTypeIds

string[]

The vehicleTypeIds that can be used to service this trip. These vehicleTypeIds must exist in the VehicleTypes passed in ProblemData for this problem.

Example: {"0":"550e8400-e29b-41d4-a716-446655440000","1":"550e8400-e29b-41d4-a716-446655440001"}

fixedVehicleId

string | null

Optional. Pin this trip to a specific vehicle: the solve must use this vehicle for both the pickup and the delivery. The vehicleId must exist in the Vehicles passed in ProblemData. If the pin cannot be satisfied - the vehicle does not exist, or its type is excluded by this trip's vehicleTypeIds - the trip is returned unassigned rather than served by a different vehicle. Leave null for no pin.

Example: 550e8400-e29b-41d4-a716-446655440000

minPickupTimeInt

integer | null · min: 0

An integer value representing the earliest time this trip can be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup.

Example: 10

Default: null

minPickupTimeStr

string | null

A string value representing the earliest time this trip can be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 12:00:00am

Default: null

minPickupDayInt

integer | null · min: 0

An integer value representing the earliest day this trip can be picked up. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup.

Example: 1

Default: null

maxPickupTimeInt

integer | null · min: 0

An integer value representing the latest time this trip can be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup.

Example: 100

Default: null

maxPickupTimeStr

string | null

A string value representing the latest time this trip can be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 11:59:59pm

Default: null

maxPickupDayInt

integer | null · min: 0

An integer value representing the latest day this trip can be picked up. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup.

Example: 1

Default: null

exactPickupTimeInt

integer | null · min: 0

An integer value representing the exact time this trip must be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup.

Example: 15

Default: null

exactPickupTimeStr

string | null

A string value representing the exact time this trip must be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 12:15:00am

Default: null

exactPickupDayInt

integer | null · min: 0

An integer value representing the exact day this trip must be picked up. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on pickup.

Example: 1

Default: null

minDeliveryTimeInt

integer | null · min: 0

An integer value representing the earliest time this trip can be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery.

Example: 20

Default: null

minDeliveryTimeStr

string | null

A string value representing the earliest time this trip can be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 12:30:00am

Default: null

minDeliveryDayInt

integer | null · min: 0

An integer value representing the earliest day this trip can be delivered. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on delivery.

Example: 1

Default: null

maxDeliveryTimeInt

integer | null · min: 0

An integer value representing the latest time this trip can be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery.

Example: 200

Default: null

maxDeliveryTimeStr

string | null

A string value representing the latest time this trip can be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 11:59:59pm

Default: null

maxDeliveryDayInt

integer | null · min: 0

An integer value representing the latest day this trip can be delivered. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on delivery.

Example: 1

Default: null

exactDeliveryTimeInt

integer | null · min: 0

An integer value representing the exact time this trip must be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery.

Example: 50

Default: null

exactDeliveryTimeStr

string | null

A string value representing the exact time this trip must be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 01:00:00am

Default: null

exactDeliveryDayInt

integer | null · min: 0

An integer value representing the exact day this trip must be delivered. Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on delivery.

Example: 1

Default: null

demand

integer · min: 0

The amount of vehicle capacity this trip consumes.

Example: 10

Default: 1

excessTravelTime

number | null · min: 0

Maximum minutes the actual pickup->delivery transit may exceed the direct travel time for this trip (caps detours from pooling). Null = no cap.

Example: 20

pickupServiceDuration

number · float · min: 0

Minutes to service the pickup (e.g. park and load) at the trip's origin. Charged at the pickup stop. Defaults to 0.

Example: 3

Default: 0

deliveryServiceDuration

number · float · min: 0

Minutes to service the drop-off (e.g. park and unload) at the trip's destination. Charged at the delivery stop. Defaults to 0.

Example: 2

Default: 0

Vehicle

vehicleId

string · required

A unique identifier for this vehicle, represented as a UUID.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleTypeId

string · required

The vehicleTypeId for this vehicle. This vehicleTypeId must exist in the VehicleTypes passed in ProblemData for this problem.

Example: 550e8400-e29b-41d4-a716-446655440000

startLocationId

string · required

The locationId of the depot for this vehicle type. This locationId must exist in the Locations passed in ProblemData for this problem.

vehicleName

string

A name for this vehicle (optional).

Example: Truck 1

fixedCost

number · float · min: 0

The fixed cost for using this vehicle.

Example: 100

Default: 0

minStartTimeInt

integer | null · min: 0

An integer value representing the earliest time this vehicle can depart from its depot to begin its route(s) (time t=0 is the earliest start time). Leave empty if there are no restrictions on when the vehicle can start.

Example: 0

Default: 0

minStartTimeStr

string | null

A string value representing the earliest time this vehicle can depart from its depot to begin its route(s). Leave empty if there are no restrictions on when the vehicle can start. The time format should match the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 12:00:00am

Default: null

minStartDayInt

integer | null · min: 0

An integer value representing the earliest day this vehicle can depart from its depot to begin its route(s). Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on when the vehicle can start.

Example: 0

Default: 0

maxEndTimeInt

integer | null · min: 0

An integer value representing the latest time this vehicle must return to its depot after completing its route(s) (time t=0 is the earliest start time). Leave empty if there are no restrictions on when the vehicle must finish.

Example: 100

Default: null

maxEndTimeStr

string | null

A string value representing the latest time this vehicle must return to its depot after completing its route(s). Leave empty if there are no restrictions on when the vehicle must finish. The time format should match the timeFormat field in ProblemData.timeSettings.

Example: 2024-01-01 11:59:59pm

Default: null

maxEndDayInt

integer | null · min: 0

An integer value representing the latest day this vehicle must return to its depot after completing its route(s). Only relevant if ProblemData.timeSettings.multipleDays is true and ProblemData.timeSettings.timeUnit is "clock". Leave empty if there are no restrictions on when the vehicle must finish.

Example: 1

Default: 0

endLocationId

string

The locationId of the depot for this vehicle type. If null, then the startLocationId will be used as the end location. This locationId must exist in the Locations passed in ProblemData for this problem.

Default: null

color

string

The color to use for this vehicle in the output. Accepts a hex code ("#FF0000") or a CSS color name ("crimson").

Example: #FF0000

Default: #FFFFFF

VehicleType

vehicleTypeId

string · required

A unique identifier for this vehicle type.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleType

string

A name for this vehicle type.

Example: Truck

capacity

integer · min: 0

The maximum capacity of this vehicle type, in units of demand. Leave null if this vehicle type has no capacity limit.

Example: 10

Default: null

allowResupply

boolean

Whether this vehicle type can be resupplied during an optimization run.

Default: false

TravelCost

This schema defines a travel cost between two locations. The travel cost can be used to specify the duration, distance, and cost of travel between two locations. An entry is required in this table for each pair of locations in the locations table.

fromLocationId

string · required

The locationId of the origin location for this travel cost. This locationId must exist in the Locations passed in ProblemData for this problem.

Example: 550e8400-e29b-41d4-a716-446655440000

toLocationId

string · required

The locationId of the destination location for this travel cost. This locationId must exist in the Locations passed in ProblemData for this problem.

Example: 550e8400-e29b-41d4-a716-446655440001

vehicleTypeId

string

The vehicleTypeId for this travel cost. This vehicleTypeId must exist in the VehicleTypes passed in ProblemData for this problem. If null, then the travel cost will apply to all vehicle types.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleType

string

The name of the vehicle type for this travel cost. This field is optional and is provided for convenience only.

Example: Truck

duration

number | null · float · min: 0

The travel duration between these two locations. If using integer time, then this should be in integer time units. If using clock time, then this should provided in seconds. If null, then the travel duration will be calculated automatically based on the latitude and longitude of the locations.

Example: 15

Default: null

distance

number | null · float · min: 0

The travel distance between these two locations. If null, then the travel distance will be calculated automatically based on the latitude and longitude of the locations. Any arbitrary unit can be used for distance, but the unit should be consistent across all entries.

Example: 10

Default: null

cost

number | null · float · min: 0

The cost of travel between these two locations.

Example: 1.5

Default: null

ApiResponse

code

integer

type

string

message

string

RequestAccepted

problemId

string

The unique identifier for this optimization run. You will want to store this locally so that you can use in your GET request for /problem.

ProblemStatus

status

string · enum · required

The status of the optimization problem identified by the problemId parameter.

Enum values:

failed

completed

running

queued

Example: completed

ProblemResult

This schema defines the results of an optimization problem. The actual fields returned will depend on the type of optimization problem submitted.

problemId

string · required

The unique identifier for this optimization run.

Example: 550e8400-e29b-41d4-a716-446655440000

ProblemStatus

The status of the optimization problem identified by the problemId parameter.

ProblemMetaData

Metadata about the optimization problem

RouteStop[]

A list of stops that were visited by vehicles during the optimization run. Each stop represents a location that was visited by a vehicle.

RouteStopFull[]

A list of stops that were visited by vehicles during the optimization run, along with additional details about the location and vehicle.

UnassignedLocation[]

A list of locations that were not visited by any vehicle during the optimization run.

UnassignedLocationFull[]

A list of locations that were not visited by any vehicle during the optimization run, along with additional details about the location.

UnassignedTrip[]

A list of trips that were not serviced by any vehicle during the optimization run.

UnassignedTripFull[]

A list of trips that were not serviced by any vehicle during the optimization run, along with additional details about the trip.

paths

A list of paths taken by vehicles during the optimization run. Each path represents a sequence of stops made by a vehicle.

Default: {}

VehicleUsage[]

A list of vehicle usage summaries for the optimization run.

Default: []

VehicleUsage

Summarizes whether a vehicle was used during the optimization run and the fixed cost it incurred.

vehicleId

string · required

The unique identifier of the vehicle.

Example: 550e8400-e29b-41d4-a716-446655440000

used

boolean · required

Whether the vehicle was used (assigned at least one stop) during the optimization run.

Example: true

fixedCostIncurred

number · float · required

The fixed cost incurred by this vehicle. This equals the vehicle's fixed cost if the vehicle was used, otherwise 0.

Example: 100

VehiclesAssigned

Summary of vehicle assignment counts for an optimization run.

assigned

integer

The number of vehicles assigned at least one stop.

Example: 8

available

integer

The total number of vehicles available in the problem.

Example: 10

LocationsAssigned

Summary of location assignment counts for an optimization run.

assigned

integer

The number of locations assigned to a vehicle route.

Example: 45

total

integer

The total number of locations in the problem.

Example: 50

AssignmentSummary

High-level counts of vehicles and locations that were assigned during the optimization run.

VehiclesAssigned

Summary of vehicle assignment counts for an optimization run.

LocationsAssigned

Summary of location assignment counts for an optimization run.

RouteSummary

Aggregate travel metrics across all vehicle routes in the optimization run.

totalDistanceTraveled

number · float

Total distance traveled across all vehicle routes, in the distance units specified by the problem settings.

Example: 5555

totalMinutesTraveled

number · float

Total travel time in minutes across all vehicle routes.

Example: 6232

totalTravelCost

number · float

Total travel cost across all vehicle routes.

Example: 12023

CostSummary

Breakdown of fixed and variable costs for the optimization run.

fixedCost

number · float

Sum of fixed costs for all vehicles used in the solution.

Example: 500

travelCost

number · float

Sum of distance- or time-based travel costs across all routes.

Example: 12023

TimingSummary

Timing information for the optimization run.

solveTime

number · float

Wall-clock time in seconds taken by the solver to produce a solution.

Example: 3.47

ResultSummary

A high-level summary of the optimization result, covering assignments, route metrics, costs, and solve timing.

AssignmentSummary

High-level counts of vehicles and locations that were assigned during the optimization run.

RouteSummary

Aggregate travel metrics across all vehicle routes in the optimization run.

CostSummary

Breakdown of fixed and variable costs for the optimization run.

TimingSummary

Timing information for the optimization run.

ProblemResponse

The complete response for a solved optimization problem, combining the full result data with a high-level summary.

ProblemResult · required

The full optimization result including routes, stops, and unassigned locations.

ResultSummary

A high-level summary of key metrics from the optimization run.

CostMatrixResponse

The response schema for a cost matrix calculation request. This includes the travel costs and any errors encountered during the calculation.

object[]

A list of travel costs between pairs of locations. Each travel cost represents the duration, distance, and cost of travel between two locations.

object[]

A list of errors encountered during the cost matrix calculation. Each error represents a problem with calculating the travel cost between two locations.

TravelCostResponses

object[]

This schema defines the response for travel costs between pairs of locations.

fromLocationId

string · required

The locationId of the origin location for this travel cost

Example: 550e8400-e29b-41d4-a716-446655440000

toLocationId

string · required

The locationId of the destination location for this travel cost.

Example: 550e8400-e29b-41d4-a716-446655440001

fromLocationName

string

The name of the origin location for this travel cost.

Example: Chicago

toLocationName

string

The name of the destination location for this travel cost.

Example: Indianapolis

vehicleTypeId

string

The vehicleTypeId for this travel cost. If null, then the travel cost will apply to all vehicle types.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleType

string

The name of the vehicle type for this travel cost. If null, then the travel cost will apply to all vehicle types.

Example: Truck

duration

number | null · float

The travel duration between these two locations.

distance

number | null · float

The travel distance between these two locations.

cost

number | null · float

The cost of travel between these two locations.

status

string · enum

The status of the travel cost calculation. This will be "s" for success, "e" for error, and "w" for warning (i.e. calculated with a fallback method).

Enum values:

Example: s

Default: s

errorMessage

string | null

If an error was encountered during the calculation of this travel cost, this field will contain a human-readable message describing the error. If no error was encountered, this field will be null.

Example: null

Default: null

TravelCostErrors

object[]

This schema defines an error encountered during the cost matrix calculation. Each error represents a problem with calculating the travel cost between two locations.

errorMessage

string · enum · required

A human-readable message describing the error encountered during the cost matrix calculation.

Enum values:

Missing latitude or longitude for at least one location.

Invalid vehicle type specified for at least one entry.

Routing service unavailable.

Unable to calculate travel cost between at least one pair of locations.

Unknown error.

errorDescription

string | null

A more detailed description of the error encountered during the cost matrix calculation.

Example: One or both locations are missing latitude or longitude.

RouteStop

A route stop represents a location that was visited by a vehicle during the optimization run.

stopId

string · required

A unique identifier for this stop, represented as a UUID.

Example: 550e8400-e29b-41d4-a716-446655440000

locationId

string · required

The locationId of the stop.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleId

string · required

The vehicleId of the vehicle that visited this stop.

Example: 660e8400-e29b-41d4-a716-446655440000

travelCostTo

number · float · required

The cost of stopping at this location, including the travel cost incurred to get to this location.

Example: 5

serviceDuration

number · float · min: 0 · required

The amount of time the vehicle spent servicing this stop.

Example: 15.5

Default: 0

stopNumber

integer · required

The stop number for this stop in the route. This is a 1-based index.

Example: 1

capacityServed

integer · required

The amount of capacity served at this stop.

Example: 10

tripId

string

The tripId of the trip that visited this stop, if applicable for this problem type.

Example: 550e8400-e29b-41d4-a716-446655440000

arrivalTimeInt

integer | null

The time at which the vehicle arrived at this stop, in integer time units. This is the number of time units from the start of the optimization run.

Example: 10

arrivalTimeStr

string | null

The time at which the vehicle arrived at this stop, in the clock time format specified in the ProblemData.timeSettings.timeFormat field.

Example: 2024-01-01 12:00:00am

Default: null

departureTimeInt

integer | null

The time at which the vehicle departed from this stop, in integer time units. This is the number of time units from the start of the optimization run.

Example: 12

Default: null

departureTimeStr

string | null

The time at which the vehicle departed from this stop, in the clock time format specified in the ProblemData.timeSettings.timeFormat field.

Example: 2024-01-01 12:15:00am

Default: null

waitDurationStart

number · float · min: 0

The amount of time the vehicle waited at this stop before servicing the location.

Example: 2.5

Default: 0

waitDurationEnd

number · float · min: 0

The amount of time the vehicle waited at this stop after servicing the location.

Example: 3

Default: 0

stopType

string · enum

The type of stop. This indicates whether the stop is a location visit, pickup, delivery, route start, route end, break start, break end, or restock.

Enum values:

location_visit

pickup

delivery

route_start

route_end

break_start

break_end

restock

Example: pickup

action

string

The action taken at this stop. This is a human-readable description of the action taken at this stop, such as "Pickup 5 passengers at Chicago for Trip 1" or "Deliver 10 packages to New York".

Example: Pickup 5 passengers at Chicago for Trip 1

travelDurationFromPreviousStop

number · float

The travel duration from the previous stop to this stop, in the time units specified by the problem settings.

Example: 10

travelDistanceFromPreviousStop

number · float

The travel distance from the previous stop to this stop, in the distance units specified by the problem settings.

Example: 5

RouteStopFull

A route stop represents a location that was visited by a vehicle during the optimization run, along with additional details about the location and vehicle.

stopId

string · required

A unique identifier for this stop, represented as a UUID.

Example: 550e8400-e29b-41d4-a716-446655440000

locationId

string · required

The locationId of the stop.

Example: 550e8400-e29b-41d4-a716-446655440000

vehicleId

string · required

The vehicleId of the vehicle that visited this stop.

Example: 660e8400-e29b-41d4-a716-446655440000

travelCostTo

number · float · required

The cost of stopping at this location, including the travel cost incurred to get to this location.

Example: 5

serviceDuration

number · float · min: 0 · required

The amount of time the vehicle spent servicing this stop.

Example: 15.5

Default: 0

stopNumber

integer · required

The stop number for this stop in the route. This is a 1-based index.

Example: 1

capacityServed

integer · required

The amount of capacity served at this stop.

Example: 10

locationName

string · required

The name of the location for this stop.

Example: Chicago

color

string · required

The color associated with this stop -- the serving vehicle's color, echoed back as supplied (hex code or CSS color name).

Example: #FF0000

tripId

string

The tripId of the trip that visited this stop, if applicable for this problem type.

Example: 550e8400-e29b-41d4-a716-446655440000

arrivalTimeInt

integer | null

The time at which the vehicle arrived at this stop, in integer time units. This is the number of time units from the start of the optimization run.

Example: 10

arrivalTimeStr

string | null

The time at which the vehicle arrived at this stop, in the clock time format specified in the ProblemData.timeSettings.timeFormat field.

Example: 2024-01-01 12:00:00am

Default: null

departureTimeInt

integer | null

The time at which the vehicle departed from this stop, in integer time units. This is the number of time units from the start of the optimization run.

Example: 12

Default: null

departureTimeStr

string | null

The time at which the vehicle departed from this stop, in the clock time format specified in the ProblemData.timeSettings.timeFormat field.

Example: 2024-01-01 12:15:00am

Default: null

waitDurationStart

number · float · min: 0

The amount of time the vehicle waited at this stop before servicing the location.

Example: 2.5

Default: 0

waitDurationEnd

number · float · min: 0

The amount of time the vehicle waited at this stop after servicing the location.

Example: 3

Default: 0

stopType

string · enum

The type of stop. This indicates whether the stop is a location visit, pickup, delivery, route start, route end, break start, break end, or restock.

Enum values:

location_visit

pickup

delivery

route_start

route_end

break_start

break_end

restock

Example: pickup

action

string

The action taken at this stop. This is a human-readable description of the action taken at this stop, such as "Pickup 5 passengers at Chicago for Trip 1" or "Deliver 10 packages to New York".

Example: Pickup 5 passengers at Chicago for Trip 1

travelDurationFromPreviousStop

number · float

The travel duration from the previous stop to this stop, in the time units specified by the problem settings.

Example: 10

travelDistanceFromPreviousStop

number · float

The travel distance from the previous stop to this stop, in the distance units specified by the problem settings.

Example: 5

vehicleName

string | null

The name of the vehicle serving this stop, when the user provided one. Denormalized from the submitted vehicle (like locationName) so a route sheet is readable without re-joining the input; null when the vehicle is unnamed.

Example: Truck 1

fixedVehicleId

string | null

The vehicleId this stop was pinned to via the input's fixedVehicleId, or null if it was not pinned. Lets a client tell 'this vehicle was chosen by the solver' from 'this vehicle was required', without re-joining against the request.

Example: 550e8400-e29b-41d4-a716-446655440000

UnassignedLocation

An unassigned object represents a location that was not visited by any vehicle during the optimization run.

locationId

string · required

The locationId of the unassigned location.

Example: 550e8400-e29b-41d4-a716-446655440000

demandDropped

integer · min: 0 · required

The amount of demand that was not served at this location.

Example: 10

UnassignedLocationFull

An unassigned object represents a location that was not visited by any vehicle during the optimization run, along with additional details about the location.

locationId

string · required

The locationId of the unassigned location.

Example: 550e8400-e29b-41d4-a716-446655440000

demandDropped

integer · min: 0 · required

The amount of demand that was not served at this location.

Example: 10

locationName

string · required

The name of the unassigned location.

Example: Chicago

latitude

number · float

The latitude of the unassigned location.

Example: 39.791

longitude

number · float

The longitude of the unassigned location.

Example: -89.398

isDepot

boolean

Whether this unassigned location serves only as a depot (true) or if this location should be serviced (false).

Default: false

ProcessUploadedTravelCostRequest

A request to process uploaded travel cost data.

object[] · required

An array of objects representing the uploaded travel cost data. Each object should contain the necessary fields to process the travel costs.

Location[] · required

The locations to use for processing the uploaded travel cost data.

TravelCost[] · required

The travel costs to use for processing the uploaded travel cost data.

overwriteExistingEntries

boolean · required

Whether to overwrite existing travel cost entries with the uploaded data. If true, existing entries will be replaced with the new data. If false, new entries will be added without modifying existing ones.

Default: true

VehicleType[]

The vehicle types to use for processing the uploaded travel cost data. Required only if the travel costs are dependent on vehicle types.

costSettings

CostSettings

The settings to use for calculating travel costs between locations. This includes the cost metric (duration or distance), cost multiplier, cost adder, and methods for calculating distances and durations.

ProcessUploadedTravelCostResponse

The response schema for processing uploaded travel cost data. This includes the number of entries processed and any errors encountered during the processing.

object[]

A list of travel costs that were successfully processed from the uploaded data. Each travel cost represents the duration, distance, and cost of travel between two locations.

UploadedTravelCostNotification[]

A list of notifications about the processing of the uploaded travel cost data. Each notification provides information about the processing status of each entry.

Location[]

A list of new locations that were added to the system as a result of processing the uploaded travel cost data.

VehicleType[]

A list of new vehicle types that were added to the system as a result of processing the uploaded travel cost data.

UploadedTravelCostNotification

A notification about the processing of a travel cost entry from the uploaded data. This includes information about the processing status and any errors encountered.

type

string · enum · required

The type of the processing notification for this travel cost entry.

Enum values:

success

warning

error

Example: success

message

string · required

A message providing additional information about the processing status, such as errors encountered or successful processing confirmation.

Example: Travel cost entry processed successfully.

UnassignedTrip

An unassigned trip represents a trip that was not serviced by any vehicle during the optimization run.

tripId

string · required

The tripId of the unassigned trip.

Example: 550e8400-e29b-41d4-a716-446655440000

demandDropped

integer · min: 0 · required

The amount of demand that was not able to be served by any vehicle for this trip.

Example: 10

capacityServed

integer · min: 0 · required

The amount of capacity that was served for this dropped trip. This will typically be 0, but in some cases (e.g. partial deliveries) it may be greater than 0.

Example: 0

UnassignedTripFull

An unassigned trip represents a trip that was not serviced by any vehicle during the optimization run, along with additional details about the trip.

tripId

string · required

The tripId of the unassigned trip.

Example: 550e8400-e29b-41d4-a716-446655440000

demandDropped

integer · min: 0 · required

The amount of demand that was not able to be served by any vehicle for this trip.

Example: 10

capacityServed

integer · min: 0 · required

The amount of capacity that was served for this dropped trip. This will typically be 0, but in some cases (e.g. partial deliveries) it may be greater than 0.

Example: 0

tripName

string · required

The name of the unassigned trip.

Example: Trip 1

fromLocationName

string · required

The name of the origin location for this trip.

Example: Chicago

toLocationName

string · required

The name of the destination location for this trip.

Example: Indianapolis

fromLocationId

string · required

The locationId of the origin location for this trip.

Example: 550e8400-e29b-41d4-a716-446655440000

toLocationId

string · required

The locationId of the destination location for this trip.

Example: 550e8400-e29b-41d4-a716-446655440001

fromLatitude

number · float · required

The latitude of the origin location for this trip.

Example: 39.791

fromLongitude

number · float · required

The longitude of the origin location for this trip.

Example: -89.398

toLatitude

number · float · required

The latitude of the destination location for this trip.

Example: 39.768

toLongitude

number · float · required

The longitude of the destination location for this trip.

Example: -86.158

ProblemMetaData

Metadata about the optimization problem, such as the problem type and the time settings used for the optimization run.

problemType

string · enum · required

The type of optimization problem that was run.

Enum values:

pickup-delivery

vehicle-routing

Example: vehicle-routing

submissionTimestamp

integer · int64 · required

The date and time when the optimization problem was submitted, in unix timestamp in seconds

Example: 1704067200

queueTime

number · float · required

The time spent in the queue before the optimization run started, in seconds.

Example: 5

optimizationTime

number · float

The time taken to run the optimization, in seconds.

Example: 120

CostMatrixRequest

This schema defines the request body for calculating a cost matrix. It includes the locations and travel costs to use for calculating the cost matrix.

Location[] · required

The locations to use for calculating the cost matrix.

costSettings

CostSettings · required

TravelCost[]

The travel costs to use for calculating the cost matrix. If not provided, the cost matrix will be calculated automatically based on the latitude and longitude of the locations. A partial cost matrix can be provided to avoid recalculating travel durations and distances between locations.

coordinateSystem

CoordinateSystem · enum

Enum values:

geographic

cartesian

Default: geographic

CostSettings

This schema defines the settings to use for calculating travel costs between locations. It includes the cost metric (duration or distance), cost multiplier, cost adder, and methods for calculating distances and durations.

costMetric

string · enum · required

The metric to use as the base for calculating travel costs. A multiplier and/or adder can be applied to this metric to calculate the final travel cost. If duration is selected, then the travel cost will be calculated based on the travel duration between locations. If distance is selected, then the travel cost will be calculated based on the travel distance between locations.

Enum values:

duration

distance

custom

Default: duration

CostMultiplier

The cost multiplier to apply to the base cost metric (duration or distance) to calculate the final travel cost.

CostAdder

The cost adder to apply to the base cost metric (duration or distance) to calculate the final travel cost.

autoCalculateDuration

boolean

Whether to automatically calculate travel durations between locations based on their latitude and longitude.

Default: false

autoCalculateDistance

boolean

Whether to automatically calculate travel distances between locations based on their latitude and longitude.

Default: false

distanceMethod

string · enum

The method to use for calculating distances between locations. Driving uses Open Route Service to calculate driving distances, geo uses the Haversine formula to calculate distances based on latitude and longitude, and Manhattan uses the Manhattan distance formula.

Enum values:

driving

geo

manhattan

euclidean

Default: geo

durationMethod

string · enum

The method to use for calculating durations between locations. Driving uses Open Route Service to calculate driving durations, geo uses the Haversine formula to calculate durations based on latitude and longitude, and Manhattan uses the Manhattan distance formula.

Enum values:

driving

geo

manhattan

euclidean

Default: geo

averageSpeed

number | null

Average travel speed used to turn a computed DISTANCE into a DURATION for the non-driving methods (geo, manhattan, euclidean), in distance units per hour. Ignored when durationMethod is "driving", where the road network supplies real durations.

This exists because a straight-line distance is not a time. Before it, geo durations were the distance number itself, which meant every vehicle travelled at exactly 60 mph between adjacent stops. The default of 30 suits urban and suburban work; raise it for long inter-city legs, lower it for dense city centres or mountain roads.

Example: 30

Default: 30

roadCircuityFactor

number | null

Multiplier applied to a straight-line distance when deriving DURATION, to account for roads not running as the crow flies. Affects duration only - the reported distance stays the true geodesic value the method name promises. 1.25 is a common urban rule of thumb; use 1.0 to model travel that really is direct.

Example: 1.25

Default: 1.25

CostMultiplier

This schema defines a cost multiplier to apply to the base cost metric (duration or distance) to calculate the final travel cost.

vehicleTypeDependence

boolean · required

Whether the cost multiplier should depend on the vehicle type. If true, then the cost multiplier will be applied separately for each vehicle type. If false, then the cost multiplier will be applied based on the first vehicle type in the VehicleTypes list.

Default: false

baseMultiplier

number · float

The multiplier to apply to the base cost metric (duration or distance) to calculate the final travel cost.

Example: 1.5

Default: 1

object[]

CostAdder

This schema defines a cost adder to apply to the base cost metric (duration or distance) to calculate the final travel cost.

vehicleTypeDependence

boolean · required

Whether the cost adder should depend on the vehicle type. If true, then the cost adder will be applied separately for each vehicle type. If false, then the cost adder will be applied based on the first vehicle type in the VehicleTypes list.

Default: false

baseAdder

number · float

The adder to apply to the base cost metric (duration or distance) to calculate the final travel cost.

Example: 10

Default: 0

object[]

TableLimit

maxRows

integer · required

Maximum number of rows allowed for this table

PlanLimits

TableLimit · required

Limits for locations table

TableLimit · required

Limits for trips table

TableLimit · required

Limits for vehicles table

TableLimit · required

Limits for vehicle types table

saved_scenarios

integer | null

Maximum saved scenarios (null for unlimited)

Default: null

run_history_days

integer | null

Days of run history retention (null for unlimited)

Default: null

max_concurrent_solves

integer

Maximum number of solves (queued + running) the user may have in flight at once

Default: 2

UserPlanRequest

user_id

string · required

The User ID (Clerk)

UserPlanObject

plan

string · enum · required

The name of this user's plan

Enum values:

free

professional

developer

PlanLimits · required

Structured plan limits for the user

object

Capability flags for this plan, keyed by feature (e.g. "resupply", "multi_day", "heterogeneous_travel_costs"). Only keys the plan overrides are listed; anything absent is allowed by default. The backend enforces these on /problem regardless, so treat them as a hint for disabling UI affordances up front rather than as the authority.

PublicPlan

A public, subscribable plan tier returned by GET /plans. The single source of truth for pricing/entitlement limits so the front end never restates them.

tier

string · required

Stable internal tier key (never changes), e.g. "free" or "professional".

Example: professional

planName

string | null

Customer-facing display name as configured in the Clerk dashboard, e.g. "Professional".

Example: Professional

PlanLimits

Resolved per-tier limits.

object

Capability flags keyed by feature; absent keys default to allowed.

ExampleScenarioCard

A published example scenario as a lightweight card for the gallery. Load the full scenario via /saved_scenario using instance_id.

instance_id

string · required

Unique id of the saved scenario; pass as scenarioId to /saved_scenario.

slug

string · required

Stable, URL-safe unique key ([a-z0-9-]).

scenario_name

string

Full display name of the scenario.

model_type

string

Model type, e.g. "pickup-delivery" or "vehicle-routing".

title

string

Short card heading (may be empty).

brief_description

string

1-3 sentence blurb shown under the title.

banner_image

string

Card image URL; empty when none is set.

constraints

string[]

Key constraints shown as bullets.

tags

string[]

Tags for gallery filtering and card chips.

object[]

Small stat objects, e.g. [{"Locations":17},{"Trips":12}].

industry

string

Industry/vertical for gallery filtering, e.g. "healthcare", "transportation" (empty when not set).

secondary_industries

string[]

Additional industries this example also belongs to, beside the primary industry. A gallery filter should treat an example as matching if the requested industry is the primary OR appears here. Optional and additive: an absent or empty array behaves exactly as a card with only industry set, so clients that ignore it are unaffected. Exists because some scenarios genuinely sit in two verticals - special-needs school transport is education and healthcare; roll-off container swaps are public-works and logistics - and forcing one label makes an industry page look emptier than the library actually is.

Example: {"0":"transportation"}

ExampleGeography

Where an example scenario is set, for gallery filtering.

scale

string

Derived instance size bucket: "small", "medium", or "large" (empty when not set).

constraints_tags

string[]

Constraint-shape tags for gallery filtering (e.g. "time windows", "vehicle types"), distinct from industry.

colorDimension

string · enum

Which fact this example's per-location colours encode. The same light-to-dark ramp means time of day on one example and demand on another, so a legend must read this rather than infer meaning from the swatches. "none" means the example's stops are uniform and are deliberately left uncoloured.

Enum values:

vehicle_eligibility

time_of_day

demand

none

Example: vehicle_eligibility

colorDimensionLabel

string | null

Display name for colorDimension, rendered verbatim as a legend title. Null when colorDimension is "none".

Example: Vehicle eligibility

colorScale

string | null · enum

How to render the legend: "categorical" for a swatch per group, "ramp" for an ordered light-to-dark strip. Null when colorDimension is "none".

Enum values:

categorical

ramp

Example: categorical

colorBuckets

string[]

Only the colours this example actually uses, in scale order, so a legend shows the two steps in play rather than every step of the scale. Empty when colorDimension is "none".

Example: {"0":"slategray","1":"darkkhaki"}

ExampleGeography

Where an example scenario is set, for gallery filtering.

city

string

region

string

country

string

ScenarioTables

Canonical tables of a persisted scenario (the input_object 'data' block). Rows use the canonical component-model fields (canonical names/casing) only; the front end derives display/working fields, geoJson, and denormalized coords on load. Trips reference locations by fromLocationId/toLocationId (no coordinates).

Location[]

Trip[]

Vehicle[]

VehicleType[]

TravelCost[]

RouteStop[]