> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model

> One-screen map of the objects in a V3 request and response, with a link to the guide section and the reference page that document each one.

> [!NOTE]
>
> **V3 is in beta.** General availability (GA) is planned for January 2027.

A map, not a field reference: each row names one part of a request or
response, its key fields, the guide section that explains it, and the
reference page that lists every field and type. Every endpoint shares one
`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](https://docs.solvice.io/guides/vrp/v3/api-design.md#a-request-at-a-glance) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `EvaluateRequest` | A problem and the plan to score; both required | `problem`, `plan` | [The request](https://docs.solvice.io/guides/vrp/v3/evaluate.md#the-request) | [Evaluate](https://docs.solvice.io/api-reference/routing/evaluate-an-imported-solution) |
| `SuggestRequest` | A problem, the plan to keep, suggest options | `problem`, `plan`, `options` | [The request](https://docs.solvice.io/guides/vrp/v3/suggest.md#the-request) | [Suggest](https://docs.solvice.io/api-reference/routing/suggest-best-insertions-for-the-tasks-outside-the-plan) |
| `RunRequest` | The solve body, run in the background | `problem`, `plan`, `options` | [Submit a run](https://docs.solvice.io/guides/vrp/v3/runs.md#submit-a-run) | [Submit a run](https://docs.solvice.io/api-reference/runs/submit-an-async-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](https://docs.solvice.io/guides/vrp/v3/api-design.md#a-request-at-a-glance) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `travel` | Which road data prices travel, and when | `engine`, `departure_time`, `speed_kmh` | [Options and travel](https://docs.solvice.io/guides/vrp/v3/api-design.md#options-and-travel) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `quotas[]` | A cap on tasks over a set of vehicles and a period | `id`, `vehicles`, `tasks`, `from`, `to`, `max_stops` | [Quotas](https://docs.solvice.io/guides/vrp/v3/constraints.md#quotas) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |

## 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](https://docs.solvice.io/guides/vrp/v3/api-design.md#jobs) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `shipments[]` | A pickup and a delivery on one vehicle | `id`, `pickup`, `delivery`, `load`, `priority`, `drop_cost` | [Shipments](https://docs.solvice.io/guides/vrp/v3/api-design.md#shipments) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `pickup` / `delivery` | One leg of a shipment | `id`, `location`, `service_duration_s`, `time_windows`, `target` | [Shipments](https://docs.solvice.io/guides/vrp/v3/constraints.md#shipments) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `time_windows[]` | When service may start, and what lateness costs | `from`, `to`, `per_late_hour`, `choice_cost` | [Time windows](https://docs.solvice.io/guides/vrp/v3/constraints.md#time-windows) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| Who may serve it | Hard and priced vehicle restrictions on a task | `required_skills`, `eligible_vehicles`, `tags`, `preferences`, `assignment_costs`, `service_factors` | [Vehicle eligibility](https://docs.solvice.io/guides/vrp/v3/constraints.md#vehicle-eligibility) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |

## 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](https://docs.solvice.io/guides/vrp/v3/api-design.md#vehicles-and-shifts) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `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](https://docs.solvice.io/guides/vrp/v3/constraints.md#shift-hours-and-overtime) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `start` / `end` | Where a shift begins or ends: a depot or an inline place | `depot`, `location`, `service_duration_s` | [Depots](https://docs.solvice.io/guides/vrp/v3/api-design.md#depots) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `breaks[]` | Windowed, triggered or fixed off-duty time | `type`, `duration_s`, `time_window`, `after`, `threshold_s`, `from`, `to` | [Driver breaks](https://docs.solvice.io/guides/vrp/v3/constraints.md#driver-breaks) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `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](https://docs.solvice.io/guides/vrp/v3/constraints.md#route-limits) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `depots[]` | Places to start, end or reload at, referenced by id | `id`, `location`, `service_duration_s`, `per_reload`, `max_intake` | [Multi-trip reloads](https://docs.solvice.io/guides/vrp/v3/constraints.md#multi-trip-reloads) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |

## Relations

| Object | What it holds | Key fields | Guide section | Reference |
| - | - | - | - | - |
| `relations[]` | A hard rule tying tasks together, by `type` | `type`, `stops` | [Relations](https://docs.solvice.io/guides/vrp/v3/api-design.md#relations) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| Ordering | `sequence`, `consecutive`, `tag_order` | `stops`, `tags` | [Relations](https://docs.solvice.io/guides/vrp/v3/constraints.md#relations) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| Grouping | `same_vehicle`, `same_day`, `same_route`, `compatible_vehicles`, `all_or_none` | `stops`, `tag` | [Relations](https://docs.solvice.io/guides/vrp/v3/constraints.md#relations) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| Timing | `synchronized`, `time_lag` | `stops`, `max_spread_s`, `from`, `to`, `min_s`, `max_s`, `on` | [Relations](https://docs.solvice.io/guides/vrp/v3/constraints.md#relations) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| 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](https://docs.solvice.io/guides/vrp/v3/api-design.md#relations-and-shipments) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |

## 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](https://docs.solvice.io/guides/vrp/v3/api-design.md#objective) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `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](https://docs.solvice.io/guides/vrp/v3/api-design.md#objective) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `options` (solve, run) | How long to search and what to return | `time_limit_s`, `seed`, `polyline`, `travel_fallback` | [Options and travel](https://docs.solvice.io/guides/vrp/v3/api-design.md#options-and-travel) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `options` (suggest) | How many slots to rank per task | `max_insertions`, `time_limit_s`, `travel_fallback` | [The request](https://docs.solvice.io/guides/vrp/v3/suggest.md#the-request) | [Suggest](https://docs.solvice.io/api-reference/routing/suggest-best-insertions-for-the-tasks-outside-the-plan) |

## Plan

The input of evaluate and suggest, the warm start of solve, and the `plan` every solve returns.

| Object | What it holds | Key fields | Guide section | Reference |
| - | - | - | - | - |
| `plan` | Routes in the request vocabulary | `routes` | [Warm-starting with `plan`](https://docs.solvice.io/guides/vrp/v3/api-design#warm-starting-with-plan) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `plan.routes[]` | One shift's ordered stops, optionally frozen at the front | `vehicle`, `shift`, `stops`, `locked_count` | [The plan shape](https://docs.solvice.io/guides/vrp/v3/evaluate.md#the-plan-shape) | [Evaluate](https://docs.solvice.io/api-reference/routing/evaluate-an-imported-solution) |
| `plan.routes[].stops[]` | A task or reload, by `type` | `type` (`job`, `pickup`, `delivery`, `reload`), `id`, `depot`, `pinned` | [The plan shape](https://docs.solvice.io/guides/vrp/v3/evaluate.md#the-plan-shape) | [Evaluate](https://docs.solvice.io/api-reference/routing/evaluate-an-imported-solution) |

## Response: solve and evaluate

Both return the same `SolveResponse`.

| Object | What it holds | Key fields | Guide section | Reference |
| - | - | - | - | - |
| `SolveResponse` | The result | `summary`, `routes`, `plan`, `unassigned`, `search_progress`, `warnings` | [Response](https://docs.solvice.io/guides/vrp/v3/api-design.md#response) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `summary` | Totals over the whole result | `score`, `tasks`, `time`, `distance_m`, `vehicles_used`, `shifts_used`, `search`, `timings`, `travel_estimated` | [Summary](https://docs.solvice.io/guides/vrp/v3/api-design.md#summary) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `summary.score` | The cost and its itemised breakdown | `cost`, `currency`, `violation_count`, `unassigned_priority`, `components` | [Summary](https://docs.solvice.io/guides/vrp/v3/api-design.md#summary) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `score.components` | One entry per cost term; they sum to `cost` | `time`, `distance`, `waiting`, `overtime`, `lateness`, `drop_costs`, `vehicles`, `preferences` | [Objective](https://docs.solvice.io/guides/vrp/v3/api-design.md#objective) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `routes[]` | One per shift with work | `vehicle`, `shift`, `stops`, `time`, `distance_m`, `load_peak`, `polyline`, `violations` | [Routes](https://docs.solvice.io/guides/vrp/v3/api-design.md#routes) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `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](https://docs.solvice.io/guides/vrp/v3/api-design.md#stops) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `violations[]` | A hard rule a route or stop breaks; evaluate only | `code`, `dimension`, `excess`, `unit`, `message` | [Violations](https://docs.solvice.io/guides/vrp/v3/evaluate.md#violations) | [Evaluate](https://docs.solvice.io/api-reference/routing/evaluate-an-imported-solution) |
| `unassigned[]` | Each task left out, and why | `task`, `category`, `reasons`, `relaxations` | [Unassigned tasks](https://docs.solvice.io/guides/vrp/v3/api-design.md#unassigned-tasks) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |
| `search_progress[]`, `warnings[]` | Cost over time; advisories | `elapsed_ms`, `cost` | [Search progress and warnings](https://docs.solvice.io/guides/vrp/v3/api-design.md#search-progress-and-warnings) | [Solve](https://docs.solvice.io/api-reference/routing/solve-a-vehicle-routing-problem) |

## 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](https://docs.solvice.io/guides/vrp/v3/suggest.md#the-response) | [Suggest](https://docs.solvice.io/api-reference/routing/suggest-best-insertions-for-the-tasks-outside-the-plan) |
| `suggestions[]` | One task's insertions, or why it has none | `task`, `insertions`, `reason` | [When a task gets no insertions](https://docs.solvice.io/guides/vrp/v3/suggest.md#when-a-task-gets-no-insertions) | [Suggest](https://docs.solvice.io/api-reference/routing/suggest-best-insertions-for-the-tasks-outside-the-plan) |
| `insertions[]` | One slot: where, what it costs, which vehicles could swap in | `routes`, `placements`, `delta`, `interchangeable_vehicles` | [Reading an insertion](https://docs.solvice.io/guides/vrp/v3/suggest.md#reading-an-insertion) | [Suggest](https://docs.solvice.io/api-reference/routing/suggest-best-insertions-for-the-tasks-outside-the-plan) |

## 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](https://docs.solvice.io/guides/vrp/v3/runs.md#the-life-of-a-run) | [Get the status of a run](https://docs.solvice.io/api-reference/runs/get-the-status-of-a-run), [Cancel a run](https://docs.solvice.io/api-reference/runs/cancel-a-run) |
| `links` | Where to poll, and where the plan is once `succeeded` | `self`, `result` | [Fetch the plan](https://docs.solvice.io/guides/vrp/v3/runs.md#fetch-the-plan) | [Get the plan of a run](https://docs.solvice.io/api-reference/runs/get-the-plan-of-a-run) |
| `error` | On `failed` only, in the error-body shape | `code`, `message`, `errors` | [The run](https://docs.solvice.io/guides/vrp/v3/runs.md#the-run) | [Get the status of a run](https://docs.solvice.io/api-reference/runs/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](https://docs.solvice.io/guides/vrp/v3/evaluate.md#validate-without-scoring) | [Validate solve](https://docs.solvice.io/api-reference/routing/check-a-solve-request-without-running-it) |
| `ErrorBody` | Every non-`200` from the routing service | `status`, `code`, `message`, `request_id`, `errors` | [Errors](https://docs.solvice.io/guides/vrp/v3/api-design.md#errors) | [Introduction](https://docs.solvice.io/api-reference/vrp/v3/introduction.md) |
| `errors[]` | One item per problem in a `400` | `code`, `pointer`, `message`, `limit`, `actual` | [Pointers](https://docs.solvice.io/guides/vrp/v3/api-design.md#pointers) | [Introduction](https://docs.solvice.io/api-reference/vrp/v3/introduction.md) |

## 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 |

> [card] [The V3 API model](https://docs.solvice.io/guides/vrp/v3/api-design.md)
>
> What each object means and how they fit together.

> [card] [API reference](https://docs.solvice.io/api-reference/vrp/v3/introduction.md)
>
> Request and response schema for every endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.