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

# Solve

> Submit a vehicle routing problem and receive optimized routes



## OpenAPI

````yaml vrp-v3 POST /v3/routing/solve
openapi: 3.1.0
info:
  title: Solvice Routing Solver
  description: >-
    Optimizes vehicle routes to minimize distance, time, or fleet size while
    respecting capacity, time windows, skills, and custom constraints.
  contact:
    name: Christophe Van Huele
  license:
    name: ''
  version: 3.0.0
servers: []
security: []
tags:
  - name: Routing
    description: Vehicle routing optimization
  - name: Legacy
    description: Solver2-compatible endpoints (V2)
  - name: Operations
    description: Health and diagnostics
paths:
  /v3/routing/solve:
    post:
      tags:
        - Routing
      summary: Solve a vehicle routing problem
      description: >-
        Accepts the **redesigned** V3 request schema
        ([`v3_types::SolveRequest`]).

        The handler maps it to the internal old DTO via
        [`map_v3_to_old_request`],

        then runs the existing pipeline (validate → collect_coords → matrix
        fetch →

        convert_request → solve → convert_response) and finally patches the

        `unassignment_penalty` values via [`apply_v3_problem_adjustments`].


        Endpoints still on the old schema (unchanged): `/v3/routing/evaluate`,

        `/v3/routing/suggest`, `/v3/routing/solve/stream`, `/v2/vrp/sync/solve`.
      operationId: solve_handler
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SolveRequest'
        required: true
      responses:
        '200':
          description: Solution found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolveResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Request `Content-Type` is not `application/json`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body could not be deserialized into the expected schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Matrix fetch error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Service unavailable (solver queue full or matrix provider circuit
            open)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SolveRequest:
      type: object
      description: Top-level request body for `POST /v3/routing/solve` (schema v2).
      required:
        - jobs
        - vehicles
      properties:
        depots:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Depot'
          description: Named depots.
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
          description: Jobs to serve (replaces jobs[] + shipments[]).
        locations:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/LocationDef'
          description: >-
            Optional shared location table; tasks/depots/shifts may reference by
            id.
        objective:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Objective'
              description: Objective configuration.
        options:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Options'
              description: Solver runtime / output / async options.
        relations:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Relation'
          description: Ordering, grouping, and synchronization constraints.
        vehicles:
          type: array
          items:
            $ref: '#/components/schemas/Vehicle'
          description: Available vehicles.
    SolveResponse:
      type: object
      description: Top-level response body for `POST /v3/routing/solve` (schema v2).
      required:
        - summary
        - routes
        - unassigned
      properties:
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
          description: One entry per non-empty route.
        summary:
          $ref: '#/components/schemas/Summary'
          description: Aggregate statistics for the solve run.
        unassigned:
          type: array
          items:
            $ref: '#/components/schemas/Unassigned'
          description: Tasks that could not be feasibly assigned.
    ErrorResponse:
      type: object
      description: >-
        Top-level error response body.


        Flat envelope matching the Spring Boot / Spring Cloud Gateway default,

        so clients see a single shape across the Solvice platform regardless of

        whether the gateway or the routing-solver produced the error.


        Example:

        ```json

        { "message": "At least one vehicle is required", "status": "BAD_REQUEST"
        }

        ```
      required:
        - message
        - status
      properties:
        code:
          type:
            - string
            - 'null'
          description: >-
            Stable machine-readable error code (e.g. `"UNSUPPORTED_FEATURE"`,

            `"VALIDATION_ERROR"`). Populated on the V3 validation-error path;
            `None`

            for endpoints that do not set a code.
        field:
          type:
            - string
            - 'null'
          description: >-
            JSON pointer to the offending request field, when the message names
            one

            (e.g. `"/vehicles/0/profile"`). `None` when not field-specific.
        message:
          type: string
          description: Human-readable error description.
        status:
          type: string
          description: Textual HTTP status (e.g. `"BAD_REQUEST"`, `"SERVICE_UNAVAILABLE"`).
        value:
          description: The offending value, when available.
    Depot:
      type: object
      description: A first-class depot, referenced by id from places and reloads.
      required:
        - id
        - location
      properties:
        cost_per_visit:
          type:
            - number
            - 'null'
          format: double
          description: Monetary cost per visit.
        id:
          type: string
          description: Unique depot id.
        location:
          type: array
          items:
            type: number
            format: double
          description: Depot location `[longitude, latitude]`.
        service_duration_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Dwell time per visit in seconds (was `handling_duration_s`).
        throughput:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: >-
                Cumulative throughput cap by named dimension. Absent =
                unlimited.
        windows:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TimeWindow'
          description: Opening hours. Absent = always open.
    Job:
      type: object
      description: >-
        The unified demand-side primitive.


        **Visit** (single-stop): set `location` directly on `Job`; leave
        `pickup`/`delivery` absent.

        **Shipment** (two-stop): set `pickup` + `delivery` (each a [`Stop`]);
        leave `location` absent.


        Exactly one form is valid (validated by `convert_v3`):

        - visit: `location` present, `pickup`/`delivery` absent.

        - shipment: `pickup` and `delivery` both present, `location` absent.
      required:
        - id
      properties:
        break_interruptible:
          type:
            - boolean
            - 'null'
          description: Whether a break may interrupt service here. Default `true`.
        delivery:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Stop'
              description: Shipment delivery leg. Requires `pickup`; excludes `location`.
        demand:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: >-
                Load on the vehicle (for shipments: between pickup and
                delivery).
        eligible_vehicles:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Eligibility'
              description: Hard vehicle allow/exclude.
        id:
          type: string
          description: Unique job id.
        location:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Place'
              description: >-
                Where this visit happens. Present for visits; absent for
                shipments.
        mandatory:
          type:
            - boolean
            - 'null'
          description: '`true` = must serve or infeasible. Default `false`.'
        pickup:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Stop'
              description: Shipment pickup leg. Requires `delivery`; excludes `location`.
        preferences:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Preference'
          description: Soft vehicle affinity preferences, priced.
        service_duration_s:
          type:
            - integer
            - 'null'
          format: int32
          description: On-site service time paid per job (seconds).
        setup_duration_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Setup time paid once on arrival at a new location (seconds).
        skills:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/SkillReq'
          description: >-
            Graded skill requirements (hard if no cost, soft if
            `violation_cost`).
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Grouping/relation labels only (NOT capability matching).
        time_windows:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TimeWindow'
          description: Time windows for this visit.
        unassigned_cost:
          type:
            - number
            - 'null'
          format: double
          description: Soft-drop price. Ignored if `mandatory`.
    LocationDef:
      type: object
      description: >-
        An entry in the optional shared `locations` table; tasks/depots/shifts
        may

        reference it by `id` to reuse matrix rows.
      required:
        - id
        - coordinate
      properties:
        coordinate:
          type: array
          items:
            type: number
            format: double
          description: Coordinate `[longitude, latitude]` (GeoJSON order).
        id:
          type: string
          description: Unique location id.
    Objective:
      type: object
      description: Top-level objective configuration.
      properties:
        balance:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Balance'
              description: Workload balance target.
        costs:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Costs'
              description: Monetary cost knobs.
        priorities:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/PriorityToken'
          description: |-
            Ordered priority list (highest first).
            Default `[serve_jobs, minimize_vehicles, minimize_cost]`.
        unassigned_cost:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Fleet-wide default soft-drop price; per-task `unassigned_cost`
            overrides.
    Options:
      type: object
      description: Top-level options block.
      properties:
        async:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/AsyncOptions'
              description: Async delivery options.
        output:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/OutputOptions'
              description: Response shaping options.
        runtime:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RuntimeOptions'
              description: Runtime solver options.
    Relation:
      oneOf:
        - type: object
          description: Ordering (gaps allowed), optionally interval-bounded.
          required:
            - type
          properties:
            group:
              type:
                - string
                - 'null'
            id:
              type:
                - string
                - 'null'
            job_ids:
              type:
                - array
                - 'null'
              items:
                type: string
            max_interval_s:
              type:
                - integer
                - 'null'
              format: int64
            measure_from:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/MeasureFrom'
            min_interval_s:
              type:
                - integer
                - 'null'
              format: int64
            type:
              type: string
              enum:
                - ordered
            violation_cost:
              type:
                - number
                - 'null'
              format: double
        - type: object
          description: Direct adjacency (folds the legacy `neighbor`).
          required:
            - type
          properties:
            group:
              type:
                - string
                - 'null'
            id:
              type:
                - string
                - 'null'
            job_ids:
              type:
                - array
                - 'null'
              items:
                type: string
            ordered:
              type:
                - boolean
                - 'null'
            type:
              type: string
              enum:
                - consecutive
            violation_cost:
              type:
                - number
                - 'null'
              format: double
        - type: object
          description: Same route (same physical trip).
          required:
            - type
          properties:
            group:
              type:
                - string
                - 'null'
            id:
              type:
                - string
                - 'null'
            job_ids:
              type:
                - array
                - 'null'
              items:
                type: string
            type:
              type: string
              enum:
                - same_route
            violation_cost:
              type:
                - number
                - 'null'
              format: double
        - type: object
          description: Same resource (same vehicle type/driver across routes).
          required:
            - type
          properties:
            group:
              type:
                - string
                - 'null'
            id:
              type:
                - string
                - 'null'
            job_ids:
              type:
                - array
                - 'null'
              items:
                type: string
            type:
              type: string
              enum:
                - same_resource
            violation_cost:
              type:
                - number
                - 'null'
              format: double
        - type: object
          description: Same calendar day.
          required:
            - type
          properties:
            group:
              type:
                - string
                - 'null'
            id:
              type:
                - string
                - 'null'
            job_ids:
              type:
                - array
                - 'null'
              items:
                type: string
            type:
              type: string
              enum:
                - same_day
            violation_cost:
              type:
                - number
                - 'null'
              format: double
        - type: object
          description: Synchronized starts across vehicles.
          required:
            - tasks
            - type
          properties:
            id:
              type:
                - string
                - 'null'
            max_wait_s:
              type:
                - integer
                - 'null'
              format: int64
            tasks:
              type: array
              items:
                $ref: '#/components/schemas/SyncParticipant'
            type:
              type: string
              enum:
                - synchronized
            violation_cost:
              type:
                - number
                - 'null'
              format: double
      description: >-
        A constraint between tasks. Tagged union; each variant carries only its

        valid fields. Each relation references **either** explicit `job_ids`
        **or**

        a `group` (tag) — validated not-both. `violation_cost` absent = hard.
    Vehicle:
      type: object
      description: A vehicle type available to serve tasks.
      required:
        - id
        - shifts
      properties:
        capacity:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: Named capacity dimensions.
        cost:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Cost'
              description: Per-vehicle cost overrides.
        count:
          type:
            - integer
            - 'null'
          format: int32
          description: Number of instances; response carries `{type, instance}`.
          minimum: 0
        id:
          type: string
          description: Vehicle type id; addressable.
        incompatible_dimensions:
          type:
            - array
            - 'null'
          items:
            type: array
            items:
              type: string
          description: Typed pairs of dimensions that cannot be carried simultaneously.
        limits:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/VehicleLimits'
              description: Hard operating limits.
        preferred_tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagPreference'
          description: Soft tag preferences (replaces `region`).
        profile:
          type:
            - string
            - 'null'
          description: Routing profile (default `"car"`); refs profiles by name.
        shifts:
          type: array
          items:
            $ref: '#/components/schemas/Shift'
          description: One or more working shifts.
        skills:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Capabilities the vehicle provides.
    Route:
      type: object
      description: A single vehicle's route.
      required:
        - vehicle
        - distance_m
        - duration_s
        - overtime_s
        - stops
      properties:
        distance_m:
          type: integer
          format: int64
          description: Total route distance, in metres.
        duration_s:
          type: integer
          format: int64
          description: Total route travel duration, in seconds.
        load_peak:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: Peak load reached on the route, by named dimension.
        overtime_s:
          type: integer
          format: int32
          description: Seconds of overtime past the soft shift end (`0` when within shift).
        stops:
          type: array
          items:
            $ref: '#/components/schemas/StopOutput'
          description: Ordered stops, including depot bookends.
        vehicle:
          $ref: '#/components/schemas/VehicleRef'
          description: The concrete vehicle instance serving this route.
    Summary:
      type: object
      description: Aggregate statistics for a completed solve.
      required:
        - status
        - vehicles_used
        - jobs_assigned
        - jobs_unassigned
        - total_distance_m
        - total_duration_s
        - estimated_cost
        - elapsed_ms
        - iterations
      properties:
        balance:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BalanceReport'
              description: Workload-balance report (absent in Phase 1).
        elapsed_ms:
          type: integer
          format: int64
          description: Wall-clock time taken by the entire request, in milliseconds.
          minimum: 0
        estimated_cost:
          $ref: '#/components/schemas/EstimatedCost'
          description: Estimated objective cost (always present).
        iterations:
          type: integer
          format: int64
          description: Number of ALNS iterations completed within the time budget.
          minimum: 0
        jobs_assigned:
          type: integer
          format: int32
          description: Number of jobs assigned to a route.
          minimum: 0
        jobs_unassigned:
          type: integer
          format: int32
          description: Number of jobs left unassigned.
          minimum: 0
        status:
          $ref: '#/components/schemas/SolveStatus'
          description: Overall outcome.
        total_distance_m:
          type: integer
          format: int64
          description: Sum of all route distances, in metres.
        total_duration_s:
          type: integer
          format: int64
          description: Sum of all route travel durations, in seconds.
        vehicles_used:
          type: integer
          format: int32
          description: Number of routes with at least one task stop.
          minimum: 0
    Unassigned:
      type: object
      description: A job the solver could not assign to any vehicle.
      required:
        - job_id
        - reasons
        - relaxations
      properties:
        job_id:
          type: string
          description: The unassigned job id.
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/UnassignedReason'
          description: Structured reasons the job could not be served.
        relaxations:
          type: array
          items:
            $ref: '#/components/schemas/Relaxation'
          description: Best-effort relaxation suggestions (empty in Phase 1).
    BTreeMap:
      type: object
      additionalProperties:
        type: integer
        format: int32
      propertyNames:
        type: string
    TimeWindow:
      type: object
      description: |-
        A time-window constraint. Per-side costs grade it from hard to soft:
        absent cost on a side = hard on that side.
      required:
        - from
        - to
      properties:
        earliness_cost_per_hour:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Cost per hour of earliness before `from`. `None` = hard on the early
            side.
        from:
          type: string
          description: Earliest allowed arrival (ISO 8601 instant).
        lateness_cost_per_hour:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Cost per hour of lateness after `to`. `None` = hard on the late
            side.
        to:
          type: string
          description: Latest allowed arrival (ISO 8601 instant).
    Stop:
      type: object
      description: 'One stop of a job: either the single `stop`, or a shipment leg.'
      required:
        - location
      properties:
        break_interruptible:
          type:
            - boolean
            - 'null'
          description: Whether a break may interrupt service here. Default `true`.
        id:
          type:
            - string
            - 'null'
          description: >-
            Stop id. Defaults to the job id (single) or
            `"{task}:pickup|:delivery"`.
        location:
          $ref: '#/components/schemas/Place'
          description: Where this stop happens.
        service_duration_s:
          type:
            - integer
            - 'null'
          format: int32
          description: On-site service time paid per job (seconds).
        setup_duration_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Setup time paid once on arrival at a new location (seconds).
        time_windows:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TimeWindow'
          description: Time windows for this stop.
    Eligibility:
      type: object
      description: 'Hard vehicle eligibility: whitelist or blacklist (mutually exclusive).'
      properties:
        allowed:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Hard whitelist of vehicle ids. Omit = all vehicles allowed.
        excluded:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Hard blacklist of vehicle ids. Mutually exclusive with `allowed`.
    Place:
      oneOf:
        - type: object
          description: Inline coordinate `[longitude, latitude]` (GeoJSON order).
          required:
            - coordinate
          properties:
            coordinate:
              type: array
              items:
                type: number
                format: double
              description: Inline coordinate `[longitude, latitude]` (GeoJSON order).
        - type: object
          description: Reference into the shared `locations[]` table by id.
          required:
            - location_id
          properties:
            location_id:
              type: string
              description: Reference into the shared `locations[]` table by id.
        - type: object
          description: Reference to a depot by id.
          required:
            - depot
          properties:
            depot:
              type: string
              description: Reference to a depot by id.
      description: >-
        A place: an inline coordinate, or a reference into `locations[]` /
        `depots[]`.


        Discriminated by which key is present (not a `type` tag):

        - `{ "coordinate": [lon, lat] }`

        - `{ "location_id": "loc-1" }`

        - `{ "depot": "depot-north" }`
    Preference:
      type: object
      description: A soft vehicle affinity preference, priced.
      required:
        - vehicle
        - violation_cost
      properties:
        vehicle:
          type: string
          description: Preferred vehicle id.
        violation_cost:
          type: number
          format: double
          description: Cost incurred when a different vehicle serves the job.
    SkillReq:
      type: object
      description: >-
        A graded skill requirement. `violation_cost` absent = hard; present =
        soft.
      required:
        - name
      properties:
        name:
          type: string
          description: >-
            Skill name the assigned vehicle must (hard) or should (soft)
            provide.
        violation_cost:
          type:
            - number
            - 'null'
          format: double
          description: Soft violation cost. `None` = hard requirement.
    Balance:
      type: object
      description: Fairness / workload-balance target, priced.
      required:
        - metric
        - cost_per_unit_spread
      properties:
        cost_per_unit_spread:
          type: number
          format: double
          description: Cost per unit of spread between the busiest and least-busy routes.
        metric:
          $ref: '#/components/schemas/BalanceMetric'
          description: What to balance.
    Costs:
      type: object
      description: Monetary cost knobs for the objective layer (fleet defaults).
      properties:
        currency:
          type:
            - string
            - 'null'
          description: Informational currency label, echoed in the response.
        per_late_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of lateness. `0`/absent = hard windows.
        per_overtime_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of overtime.
        per_service_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of on-site service time.
        per_travel_hour:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Cost per hour of travel time. Omitting `costs` ⇒ cost ≈ travel
            seconds.
        per_travel_km:
          type:
            - number
            - 'null'
          format: double
          description: Cost per kilometre of travel distance.
        per_wait_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of waiting time.
    PriorityToken:
      type: string
      description: Priority token in the objective priority list.
      enum:
        - serve_jobs
        - minimize_vehicles
        - minimize_cost
    AsyncOptions:
      type: object
      description: Async delivery options.
      properties:
        webhook_url:
          type:
            - string
            - 'null'
          description: Webhook URL to receive the solution when async solve completes.
    OutputOptions:
      type: object
      description: Response shaping options.
      properties:
        arrival_snap_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Snap arrivals to the nearest multiple of this many seconds.
          minimum: 0
        polylines:
          type:
            - boolean
            - 'null'
          description: Whether to include encoded route polylines.
    RuntimeOptions:
      type: object
      description: Runtime (non-goal) solver options.
      properties:
        matrix:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/MatrixInput'
              description: Caller-supplied distance/duration matrix.
        seed:
          type:
            - integer
            - 'null'
          format: int64
          description: Random seed for reproducible solves.
          minimum: 0
        time_limit_ms:
          type:
            - integer
            - 'null'
          format: int64
          description: Wall-clock budget in milliseconds.
          minimum: 0
        traffic:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/TrafficOptions'
              description: Traffic-aware matrix options.
    MeasureFrom:
      type: string
      description: Which time reference an `Ordered` interval is measured from.
      enum:
        - arrival
        - departure
    SyncParticipant:
      type: object
      description: A participant in a `Synchronized` relation.
      required:
        - id
      properties:
        id:
          type: string
          description: Task id.
        vehicles:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Compatible vehicle ids for this participant.
    Cost:
      type: object
      description: Per-vehicle cost overrides; `objective.costs` are the fleet defaults.
      properties:
        fixed:
          type:
            - number
            - 'null'
          format: double
          description: One-time cost when the vehicle is used.
        per_km:
          type:
            - number
            - 'null'
          format: double
          description: Cost per kilometre driven.
        per_overtime_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of overtime.
        per_service_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of on-site service time.
        per_shift:
          type:
            - number
            - 'null'
          format: double
          description: Startup cost per activated shift.
        per_stop:
          type:
            - number
            - 'null'
          format: double
          description: Cost per completed stop.
        per_travel_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour of travel time.
        per_wait_hour:
          type:
            - number
            - 'null'
          format: double
          description: Cost per hour spent waiting.
        standby:
          type:
            - number
            - 'null'
          format: double
          description: Cost when rostered and unused (was `unused`).
    VehicleLimits:
      type: object
      description: Vehicle distance/time limits.
      properties:
        max_distance_m:
          type:
            - integer
            - 'null'
          format: int64
          description: Hard maximum distance in metres.
        max_drive_time_s:
          type:
            - integer
            - 'null'
          format: int64
          description: Hard maximum drive time in seconds.
        max_duty_time_s:
          type:
            - integer
            - 'null'
          format: int64
          description: Hard maximum duty time in seconds.
        max_leg_drive_time_s:
          type:
            - integer
            - 'null'
          format: int64
          description: Hard maximum single drive leg in seconds.
    TagPreference:
      type: object
      description: A soft tag preference, priced (replaces `region`).
      required:
        - tag
        - violation_cost
      properties:
        tag:
          type: string
          description: Preferred tag.
        violation_cost:
          type: number
          format: double
          description: Cost incurred when a task without this tag is served.
    Shift:
      type: object
      description: One working shift for a vehicle.
      required:
        - from
        - to
      properties:
        breaks:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Break'
          description: Scheduled breaks within this shift.
        capacity:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: Per-shift capacity override (overrides `vehicle.capacity`).
        end:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Place'
              description: End place. Absent = open end.
        from:
          type: string
          description: Shift start (ISO 8601 instant).
        max_overtime_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Maximum allowed overtime beyond `to` in seconds.
        max_tasks:
          type:
            - integer
            - 'null'
          format: int32
          description: Max tasks in this shift.
          minimum: 0
        reloads:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Reload'
          description: Multi-trip reload stops.
        serves_tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Shift only serves tasks whose tags match (was shift `tags`).
        start:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Place'
              description: Start place. Absent = open start.
        to:
          type: string
          description: Shift end (ISO 8601 instant; hard unless `max_overtime_s` set).
        unload_before_end:
          type:
            - boolean
            - 'null'
          description: Vehicle must visit the end depot to unload before closing time.
    StopOutput:
      type: object
      description: A single stop within a route.
      required:
        - type
        - location
      properties:
        arrival:
          type:
            - string
            - 'null'
          description: >-
            Arrival time (ISO 8601), or `None` when the problem has no time
            windows.
        departure:
          type:
            - string
            - 'null'
          description: >-
            Departure time (ISO 8601), or `None` when the problem has no time
            windows.
        depot:
          type:
            - string
            - 'null'
          description: Depot id for `start`/`end`/`reload` stops.
        id:
          type:
            - string
            - 'null'
          description: Task/stop id served here. `None` for depot/break stops.
        lateness_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Seconds late beyond the latest allowed arrival (`0` when on time).
        load_after:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BTreeMap'
              description: Cumulative load carried after this stop, by named dimension.
        location:
          type: array
          items:
            type: number
            format: double
          description: Stop location `[longitude, latitude]` (GeoJSON order).
        service_s:
          type:
            - integer
            - 'null'
          format: int32
          description: On-site service time at this stop, in seconds.
        snapped_location:
          type:
            - array
            - 'null'
          items:
            type: number
            format: double
          description: The same point snapped to the routable graph, when available.
        travel_distance_m:
          type:
            - integer
            - 'null'
          format: int32
          description: Travel distance from the previous stop, in metres.
        travel_time_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Travel time from the previous stop, in seconds.
        type:
          $ref: '#/components/schemas/StopType'
          description: What kind of stop this is.
        wait_s:
          type:
            - integer
            - 'null'
          format: int32
          description: Seconds spent waiting for the time window to open here.
    VehicleRef:
      type: object
      description: Identifies a concrete vehicle instance in the response.
      required:
        - type
        - instance
      properties:
        instance:
          type: integer
          format: int32
          description: 1-based instance index within the type (from `count` expansion).
          minimum: 0
        type:
          type: string
          description: Vehicle type id (the `vehicle.id` from the request).
    BalanceReport:
      type: object
      description: Workload-balance report across routes.
      required:
        - metric
        - min
        - max
        - stdev
      properties:
        max:
          type: integer
          format: int64
          description: Maximum per-route value of the metric.
        metric:
          $ref: '#/components/schemas/BalanceMetric'
          description: The metric being balanced.
        min:
          type: integer
          format: int64
          description: Minimum per-route value of the metric.
        stdev:
          type: number
          format: double
          description: Standard deviation of the metric across routes.
    EstimatedCost:
      type: object
      description: The estimated objective cost of a solution, always present.
      required:
        - total
        - components
      properties:
        components:
          $ref: '#/components/schemas/CostComponents'
          description: Per-component breakdown.
        currency:
          type:
            - string
            - 'null'
          description: >-
            Informational currency label, echoed from
            `objective.costs.currency`.
        total:
          type: number
          format: double
          description: Total estimated cost (sum of `components`).
    SolveStatus:
      type: string
      description: Overall solve outcome.
      enum:
        - solved
        - partial
        - infeasible
    UnassignedReason:
      type: object
      description: A machine-readable reason a task could not be assigned.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Stable machine code, e.g. `CAPACITY_EXCEEDED`,
            `TIME_WINDOW_VIOLATED`.
        detail:
          description: Optional structured detail (e.g. the relaxation needed).
        message:
          type: string
          description: Human-readable explanation.
    Relaxation:
      type: object
      description: A best-effort suggestion for relaxing the problem to assign a task.
      required:
        - field
        - suggestion
      properties:
        field:
          type: string
          description: JSON pointer to the field that would need relaxing.
        suggestion:
          type: string
          description: Human-readable suggestion.
    BalanceMetric:
      type: string
      description: Balance metric for workload fairness.
      enum:
        - duration
        - distance
        - stops
        - load
    MatrixInput:
      type: object
      description: A caller-supplied N×N distance/duration matrix.
      required:
        - distances
        - durations
      properties:
        distances:
          type: array
          items:
            type: array
            items:
              type: integer
              format: int32
          description: Row-major N×N distance matrix in metres.
        durations:
          type: array
          items:
            type: array
            items:
              type: integer
              format: int32
          description: Row-major N×N duration matrix in seconds.
    TrafficOptions:
      type: object
      description: Traffic-aware matrix options. Presence enables traffic.
      properties:
        departure_time:
          type:
            - string
            - 'null'
          description: Departure time for traffic lookup (ISO 8601 instant).
    Break:
      oneOf:
        - type: object
          description: Flexible break taken within optional windows / after a trigger.
          required:
            - duration_s
            - type
          properties:
            duration_s:
              type: integer
              format: int32
              description: Break duration in seconds.
            location:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/Place'
                  description: Optional break location.
            paid:
              type:
                - boolean
                - 'null'
              description: Whether break time counts as paid working time.
            trigger:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BreakTrigger'
                  description: Optional drive/duty accumulator trigger.
            type:
              type: string
              enum:
                - floating
            windows:
              type:
                - array
                - 'null'
              items:
                $ref: '#/components/schemas/TimeWindow'
              description: Optional windows within which the break must be taken.
        - type: object
          description: Mandatory off-duty interval at a fixed time.
          required:
            - from
            - to
            - type
          properties:
            from:
              type: string
              description: Start of the break (ISO 8601 instant).
            location:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/Place'
                  description: Optional break location.
            paid:
              type:
                - boolean
                - 'null'
              description: Whether break time counts as paid working time.
            to:
              type: string
              description: End of the break (ISO 8601 instant).
            type:
              type: string
              enum:
                - fixed
      description: A scheduled break within a shift. Tagged by `type`.
    Reload:
      type: object
      description: A reload stop within a multi-trip shift.
      required:
        - depot
      properties:
        depot:
          type: string
          description: Id of the depot to reload at.
        max_reloads:
          type:
            - integer
            - 'null'
          format: int32
          description: Maximum number of reloads at this depot within the shift.
          minimum: 0
    StopType:
      type: string
      description: |-
        The kind of a stop in a route.

        Phase 1 emits only `Start`, `End`, and `Job`. The shipment/break/reload
        variants exist for forward compatibility and simply do not appear yet.
      enum:
        - start
        - job
        - pickup
        - delivery
        - break
        - reload
        - end
    CostComponents:
      type: object
      description: >-
        Money cost components contributing to the estimated total.


        Phase 1 populates `travel`, `vehicles_fixed`, and `unassigned`; the
        remaining

        components are reported as `0.0` until later phases wire their objective
        terms.
      required:
        - travel
        - waiting
        - overtime
        - lateness
        - vehicles_fixed
        - unassigned
        - preferences
        - imbalance
      properties:
        imbalance:
          type: number
          format: double
          description: Workload-imbalance cost.
        lateness:
          type: number
          format: double
          description: Lateness cost for soft time-window violations.
        overtime:
          type: number
          format: double
          description: Overtime cost beyond the soft shift end.
        preferences:
          type: number
          format: double
          description: Soft preference (vehicle/tag affinity) violation cost.
        travel:
          type: number
          format: double
          description: Travel cost (distance- and/or time-proportional).
        unassigned:
          type: number
          format: double
          description: Penalty cost of unassigned jobs.
        vehicles_fixed:
          type: number
          format: double
          description: Fixed per-vehicle (activation) cost.
        waiting:
          type: number
          format: double
          description: Cost of waiting for time windows to open.
    BreakTrigger:
      type: object
      description: A drive/duty accumulator trigger for a floating break.
      required:
        - after
        - threshold_s
      properties:
        after:
          $ref: '#/components/schemas/TriggerAfter'
          description: 'What to accumulate: drive time or duty time.'
        resets_accumulator:
          type:
            - boolean
            - 'null'
          description: Whether the accumulator resets after the break.
        threshold_s:
          type: integer
          format: int64
          description: Trigger threshold in seconds.
    TriggerAfter:
      type: string
      description: What a break trigger accumulates.
      enum:
        - drive
        - duty

````