V3 is in beta. General availability (GA) is planned for January 2027.
problem object; only the wrapper differs.
Request envelope
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
SolveRequest | A problem, an optional warm start, solver options | problem, plan, options | A request at a glance | Solve |
EvaluateRequest | A problem and the plan to score; both required | problem, plan | The request | Evaluate |
SuggestRequest | A problem, the plan to keep, suggest options | problem, plan, options | The request | Suggest |
RunRequest | The solve body, run in the background | problem, plan, options | Submit a run | Submit a run |
Problem
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
problem | Everything the solver may plan; vehicles plus at least one task | jobs, shipments, vehicles, depots, relations, objective, travel, quotas | A request at a glance | Solve |
travel | Which road data prices travel, and when | engine, departure_time, speed_kmh | Options and travel | Solve |
quotas[] | A cap on tasks over a set of vehicles and a period | id, vehicles, tasks, from, to, max_stops | Quotas | Solve |
Tasks
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
jobs[] | One visit at one location | id, location, service_duration_s, setup_duration_s, time_windows, delivery_load, pickup_load, priority, drop_cost, target | Jobs | Solve |
shipments[] | A pickup and a delivery on one vehicle | id, pickup, delivery, load, priority, drop_cost | Shipments | Solve |
pickup / delivery | One leg of a shipment | id, location, service_duration_s, time_windows, target | Shipments | Solve |
time_windows[] | When service may start, and what lateness costs | from, to, per_late_hour, choice_cost | Time windows | Solve |
| Who may serve it | Hard and priced vehicle restrictions on a task | required_skills, eligible_vehicles, tags, preferences, assignment_costs, service_factors | Vehicle eligibility | Solve |
Fleet
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
vehicles[] | A vehicle and what it can carry and do | id, shifts, capacity, skills, profile, costs, limits, preferred_tags, compatible_with, workload_weight | Vehicles and shifts | Solve |
shifts[] | One working period of a vehicle | id, from, to, start, end, breaks, reloads, max_overtime_s, initial_load, serves_tags | Shift hours and overtime | Solve |
start / end | Where a shift begins or ends: a depot or an inline place | depot, location, service_duration_s | Depots | Solve |
breaks[] | Windowed, triggered or fixed off-duty time | type, duration_s, time_window, after, threshold_s, from, to | Driver breaks | Solve |
limits | Hard caps on a route, per vehicle or per shift | max_distance_m, max_route_duration_s, max_leg_travel_s, max_stops, periods | Route limits | Solve |
depots[] | Places to start, end or reload at, referenced by id | id, location, service_duration_s, per_reload, max_intake | Multi-trip reloads | Solve |
Relations
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
relations[] | A hard rule tying tasks together, by type | type, stops | Relations | Solve |
| Ordering | sequence, consecutive, tag_order | stops, tags | Relations | Solve |
| Grouping | same_vehicle, same_day, same_route, compatible_vehicles, all_or_none | stops, tag | Relations | Solve |
| Timing | synchronized, time_lag | stops, max_spread_s, from, to, min_s, max_s, on | Relations | Solve |
| Shipments in relations | Name a leg by its stop id. all_or_none is the exception: it takes the shipment id and rejects leg ids, and a group that contains a shipment must form exactly one consecutive chain with no member coupled by synchronized or time_lag | {shipment}:pickup, {shipment}:delivery | Relations and shipments | Solve |
Objective and options
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
objective | Rates that turn time, distance and preferences into one cost | currency, costs, per_late_hour, per_delay_workday, grouping, workload_share | Objective | Solve |
costs | Per-unit rates; the same keys on vehicles[].costs and, minus per_used_vehicle, on shifts[].costs | per_route_hour, per_drive_hour, per_travel_km, per_wait_hour, per_overtime_hour, per_route, per_used_vehicle | Objective | Solve |
options (solve, run) | How long to search and what to return | time_limit_s, seed, polyline, travel_fallback | Options and travel | Solve |
options (suggest) | How many slots to rank per task | max_insertions, time_limit_s, travel_fallback | The request | Suggest |
Plan
The input of evaluate and suggest, the warm start of solve, and theplan every solve returns.
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
plan | Routes in the request vocabulary | routes | Warm-starting with plan | Solve |
plan.routes[] | One shift’s ordered stops, optionally frozen at the front | vehicle, shift, stops, locked_count | The plan shape | Evaluate |
plan.routes[].stops[] | A task or reload, by type | type (job, pickup, delivery, reload), id, depot, pinned | The plan shape | Evaluate |
Response: solve and evaluate
Both return the sameSolveResponse.
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
SolveResponse | The result | summary, routes, plan, unassigned, search_progress, warnings | Response | Solve |
summary | Totals over the whole result | score, tasks, time, distance_m, vehicles_used, shifts_used, search, timings, travel_estimated | Summary | Solve |
summary.score | The cost and its itemised breakdown | cost, currency, violation_count, unassigned_priority, components | Summary | Solve |
score.components | One entry per cost term; they sum to cost | time, distance, waiting, overtime, lateness, drop_costs, vehicles, preferences | Objective | Solve |
routes[] | One per shift with work | vehicle, shift, stops, time, distance_m, load_peak, polyline, violations | Routes | Solve |
routes[].stops[] | Every stop from start to end, by type | type, id, arrival, service_start, departure, wait_s, travel_s, distance_m, lateness_s, load_after | Stops | Solve |
violations[] | A hard rule a route or stop breaks; evaluate only | code, dimension, excess, unit, message | Violations | Evaluate |
unassigned[] | Each task left out, and why | task, category, reasons, relaxations | Unassigned tasks | Solve |
search_progress[], warnings[] | Cost over time; advisories | elapsed_ms, cost | Search progress and warnings | Solve |
Response: suggest
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
SuggestResponse | Ranked slots for every task not in plan | suggestions, truncated, travel_estimated, timings, warnings | The response | Suggest |
suggestions[] | One task’s insertions, or why it has none | task, insertions, reason | When a task gets no insertions | Suggest |
insertions[] | One slot: where, what it costs, which vehicles could swap in | routes, placements, delta, interchangeable_vehicles | Reading an insertion | Suggest |
Async run
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
Run | A background solve; status is queued, running, succeeded, failed or cancelled | id, status, links, started_at, finished_at, expires_at, error | The life of a run | Get the status of a run, Cancel a run |
links | Where to poll, and where the plan is once succeeded | self, result | Fetch the plan | Get the plan of a run |
error | On failed only, in the error-body shape | code, message, errors | The run | Get the status of a run |
Validation and errors
| Object | What it holds | Key fields | Guide section | Reference |
|---|---|---|---|---|
ValidateResponse | A dry run’s verdict | valid, warnings | Validate without scoring | Validate solve |
ErrorBody | Every non-200 from the routing service | status, code, message, request_id, errors | Errors | Introduction |
errors[] | One item per problem in a 400 | code, pointer, message, limit, actual | Pointers | Introduction |
Conventions
| Convention | Rule |
|---|---|
| Coordinates | [longitude, latitude], in that order |
| Datetimes | RFC 3339 with a UTC offset: 2026-04-01T08:00:00+02:00 or ...Z. No offset is a 400 |
| Durations | Seconds, suffixed _s |
| Distances | Metres, suffixed _m |
| Costs | Your own currency; objective.currency labels it |
| Closed objects | An undefined field is a 400 with an unknown_field item that names it |
The V3 API model
What each object means and how they fit together.
API reference
Request and response schema for every endpoint.