{
  "openapi": "3.1.0",
  "info": {
    "title": "Solvice Routing API",
    "description": "Every V3 Routing API endpoint: solve, evaluate and suggest, and async runs.\n\nV3 is in beta until general availability, planned for 1 December 2026. During the beta a release can rename or remove fields.\n\n**Authentication:** send your Solvice API key as the value of the `Authorization` header, with no `Bearer` prefix.\n\n**Clients:** accept response fields and enum values this file does not list. Requests are strict: an unknown field is a 400.",
    "contact": {
      "name": "Solvice",
      "url": "https://www.solvice.io"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    },
    "version": "3.0.0"
  },
  "servers": [
    {
      "url": "https://api.solvice.io",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Routing",
      "description": "Vehicle routing optimization"
    },
    {
      "name": "Runs",
      "description": "Async routing runs"
    }
  ],
  "paths": {
    "/v3/routing/evaluate": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Evaluate an imported solution",
        "description": "Scores the `plan` you send against `problem` without searching for a better one. A plan that breaks a hard rule is still a 200: each violation is listed in `violations[]` on the route or stop where it occurs and counted in `summary.score.violation_count`; only a malformed request is a 400. Returns the plan's cost, timing and loads. Tasks that appear in no route are reported in `unassigned[]`. `problem` has the same shape as on `POST /v3/routing/solve`, and a solve response's `plan` can be sent as it stands.",
        "operationId": "evaluate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, two jobs, both in the plan, straight-line travel",
                  "value": {
                    "plan": {
                      "routes": [
                        {
                          "shift": "mon",
                          "stops": [
                            {
                              "id": "job-1",
                              "type": "job"
                            },
                            {
                              "id": "job-2",
                              "type": "job"
                            }
                          ],
                          "vehicle": "v1"
                        }
                      ]
                    },
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Solution evaluated.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolveResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        },
                        {
                          "code": "conflicting_fields",
                          "message": "job 'delivery-3': drop_cost cannot be combined with priority",
                          "pointer": "/problem/jobs/2/drop_cost"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A field this endpoint does not take",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `options`, expected `problem` or `plan` at line 1 column 612",
                          "pointer": "/options"
                        }
                      ],
                      "message": "unknown field `options`, expected `problem` or `plan` at line 1 column 612",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "503": {
            "description": "The platform in front of the solver could not take the request. This endpoint takes no solver slot, so the solver itself never answers 503 here; the response is the API gateway's own shape, not the `ErrorBody`. Retry after `Retry-After` when the response has one, else with backoff.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the response has one."
              }
            }
          }
        }
      }
    },
    "/v3/routing/solve": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Solve a vehicle routing problem",
        "description": "Assigns the jobs and shipments in `problem` to the vehicles' shifts and returns the routes, the `plan` they follow and any tasks left unassigned, each with the reasons. A problem that cannot be fully served is still a 200: the tasks no route could take are listed in `unassigned[]`, each with its `reasons[]` and a `category`; only a malformed request is a 400, whose `errors[]` says what to fix. Travel times and distances for the request's locations are then looked up, and the search runs for up to `options.time_limit_s` seconds (default 150 ms plus 4 ms per task; maximum 60). A problem of more than 400 tasks (jobs and shipments together) is a 400: submit one of up to 10,000 tasks to `POST /v3/routing/runs`, which takes the same body. Send a previous result's `plan` to re-optimize starting from it. `POST /v3/routing/evaluate` and `POST /v3/routing/suggest` take the same `problem`.",
        "operationId": "solve",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SolveRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, two jobs, straight-line travel",
                  "value": {
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                },
                "warm_start": {
                  "summary": "Re-optimize from a previous plan, keeping its first stop",
                  "value": {
                    "options": {
                      "time_limit_s": 2
                    },
                    "plan": {
                      "routes": [
                        {
                          "locked_count": 1,
                          "shift": "mon",
                          "stops": [
                            {
                              "id": "job-1",
                              "type": "job"
                            },
                            {
                              "id": "job-2",
                              "type": "job"
                            }
                          ],
                          "vehicle": "v1"
                        }
                      ]
                    },
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Solution found.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolveResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "actual": 600,
                          "code": "limit_exceeded",
                          "limit": 60,
                          "message": "options.time_limit_s must be <= 60, got 600",
                          "pointer": "/options/time_limit_s"
                        },
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A misspelt or unknown field",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688",
                          "pointer": "/options/time_limit"
                        }
                      ],
                      "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "502": {
            "description": "Travel times and distances could not be fetched (`code: travel_provider_error`). Retry with backoff (no `Retry-After` is sent); if it keeps failing for the same request, contact support with the `request_id`. Only with `options.travel_fallback: \"fail\"`; by default the plan is solved on estimated travel and `summary.travel_estimated` is set.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "travel_provider_error",
                  "errors": [],
                  "message": "Travel data could not be fetched from the travel provider",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "BAD_GATEWAY"
                }
              }
            }
          },
          "503": {
            "description": "No capacity right now (`code: overloaded`): every solver slot is busy, or the wait for one timed out. With `options.travel_fallback: \"fail\"`, also returned while travel lookups are suspended after repeated failures (`code: travel_provider_unavailable`). Retry after the number of seconds in the `Retry-After` header.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              },
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "overloaded",
                  "errors": [],
                  "message": "All solver slots are busy, try again later",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "SERVICE_UNAVAILABLE"
                }
              }
            }
          }
        }
      }
    },
    "/v3/routing/suggest": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Suggest best insertions for the tasks outside the plan",
        "description": "Takes the same body as `POST /v3/routing/evaluate` (`problem` + committed `plan`), plus optional `options`. A task that has no feasible position is still a 200: its `suggestions[]` entry has an empty `insertions` and a `reason`; only a malformed request is a 400. Every task of `problem` that is not in `plan` is a task to place: finds its feasible insertion positions and returns them as `insertions`, ranked by `delta.cost`, the change in the plan's cost in money. The members of a `synchronized` or `time_lag` group outside `plan` are one task to place: each insertion places every member, and with the default `on: service_start` a crew's members start within `max_spread_s` of one another (`service_start`); a `time_lag` keeps its lag. Each insertion lists the stops it adds (`placements`) and every plan route it changes, whole (`routes`): swap those routes into `plan` to apply it. An empty `insertions` carries a `reason` whose `code` is `time_limit`, `candidates_exhausted` or `infeasible` (an open set) and whose `message` says the same in English. The committed plan is never modified. Limitation: suggest never opens a new reload trip on a multi-trip vehicle.",
        "operationId": "suggest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, one job in the plan, one job to place, straight-line travel",
                  "value": {
                    "options": {
                      "max_insertions": 3
                    },
                    "plan": {
                      "routes": [
                        {
                          "shift": "mon",
                          "stops": [
                            {
                              "id": "job-1",
                              "type": "job"
                            }
                          ],
                          "vehicle": "v1"
                        }
                      ]
                    },
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Suggestions computed.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "actual": 600,
                          "code": "limit_exceeded",
                          "limit": 60,
                          "message": "options.time_limit_s must be <= 60, got 600",
                          "pointer": "/options/time_limit_s"
                        },
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A misspelt or unknown field",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `time_limit`, expected one of `max_insertions`, `time_limit_s`, `travel_fallback` at line 1 column 702",
                          "pointer": "/options/time_limit"
                        }
                      ],
                      "message": "unknown field `time_limit`, expected one of `max_insertions`, `time_limit_s`, `travel_fallback` at line 1 column 702",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "502": {
            "description": "Travel times and distances could not be fetched (`code: travel_provider_error`). Retry with backoff (no `Retry-After` is sent); if it keeps failing for the same request, contact support with the `request_id`. Only with `options.travel_fallback: \"fail\"`; by default the insertions are ranked on estimated travel and `travel_estimated` is set.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "travel_provider_error",
                  "errors": [],
                  "message": "Travel data could not be fetched from the travel provider",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "BAD_GATEWAY"
                }
              }
            }
          },
          "503": {
            "description": "No capacity right now (`code: overloaded`): every solver slot is busy, or the wait for one timed out. With `options.travel_fallback: \"fail\"`, also returned while travel lookups are suspended after repeated failures (`code: travel_provider_unavailable`). Retry after the number of seconds in the `Retry-After` header.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              },
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "overloaded",
                  "errors": [],
                  "message": "All solver slots are busy, try again later",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "SERVICE_UNAVAILABLE"
                }
              }
            }
          }
        }
      }
    },
    "/v3/routing/validate/evaluate": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Check an evaluate request without running it",
        "description": "Checks a `POST /v3/routing/evaluate` request without scoring it. Only the request's validity is judged, not whether the plan is feasible: a plan that breaks a rule still passes, and only a malformed request is a 400 (or 403). It runs the checks `POST /v3/routing/evaluate` runs before it fetches travel times, and stops there: no travel times are fetched, nothing is searched, no solver slot is taken, and the call is not billed. The body is the body of `POST /v3/routing/evaluate`. A valid request returns `{\"valid\": true, \"warnings\": []}`; an invalid one returns the 400 (or 403) the real call would. Not covered, because the real call makes these checks only after it fetches travel times: coordinates that span more than one Maps region (a 400 on the real call), and the `plan` (that its routes and stops name vehicles, shifts, tasks and depots of `problem`, and that it imports; see the plan errors in the errors guide).",
        "operationId": "validate_evaluate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EvaluateRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, two jobs, both in the plan, straight-line travel",
                  "value": {
                    "plan": {
                      "routes": [
                        {
                          "shift": "mon",
                          "stops": [
                            {
                              "id": "job-1",
                              "type": "job"
                            },
                            {
                              "id": "job-2",
                              "type": "job"
                            }
                          ],
                          "vehicle": "v1"
                        }
                      ]
                    },
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request passed every check made before travel times are fetched. `warnings` lists the advisories the real call would return that need no travel data: an `options.time_limit_s` below the 0.1 s floor (`time_limit_raised`), an option the travel engine makes inert, or plan flags evaluate ignores (`no_effect`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        },
                        {
                          "code": "conflicting_fields",
                          "message": "job 'delivery-3': drop_cost cannot be combined with priority",
                          "pointer": "/problem/jobs/2/drop_cost"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A field this endpoint does not take",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `options`, expected `problem` or `plan` at line 1 column 612",
                          "pointer": "/options"
                        }
                      ],
                      "message": "unknown field `options`, expected `problem` or `plan` at line 1 column 612",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "503": {
            "description": "The platform in front of the solver could not take the request. This endpoint takes no solver slot, so the solver itself never answers 503 here; the response is the API gateway's own shape, not the `ErrorBody`. Retry after `Retry-After` when the response has one, else with backoff.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the response has one."
              }
            }
          }
        }
      }
    },
    "/v3/routing/validate/solve": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Check a solve request without running it",
        "description": "Checks a `POST /v3/routing/solve` request without solving it. Only the request's validity is judged, not whether its tasks can all be served: an infeasible problem still passes, and only a malformed request is a 400 (or 403). It runs the checks `POST /v3/routing/solve` runs before it fetches travel times, and stops there: no travel times are fetched, nothing is searched, no solver slot is taken, and the call is not billed. The body is the body of `POST /v3/routing/solve`. A valid request returns `{\"valid\": true, \"warnings\": []}`; an invalid one returns the 400 (or 403) the real call would. Not covered, because the real call makes these checks only after it fetches travel times: coordinates that span more than one Maps region (a 400 on the real call), and the warm-start `plan` (that its routes and stops name vehicles, shifts, tasks and depots of `problem`, and that it imports, its locked stops included; see the plan errors in the errors guide).",
        "operationId": "validate_solve",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SolveRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, two jobs, straight-line travel",
                  "value": {
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request passed every check made before travel times are fetched. `warnings` lists the advisories the real call would return that need no travel data: an `options.time_limit_s` below the 0.1 s floor (`time_limit_raised`), an option the travel engine makes inert, or plan flags evaluate ignores (`no_effect`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "actual": 600,
                          "code": "limit_exceeded",
                          "limit": 60,
                          "message": "options.time_limit_s must be <= 60, got 600",
                          "pointer": "/options/time_limit_s"
                        },
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A misspelt or unknown field",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688",
                          "pointer": "/options/time_limit"
                        }
                      ],
                      "message": "unknown field `time_limit`, expected one of `time_limit_s`, `seed`, `polyline`, `travel_fallback` at line 1 column 688",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "503": {
            "description": "The platform in front of the solver could not take the request. This endpoint takes no solver slot, so the solver itself never answers 503 here; the response is the API gateway's own shape, not the `ErrorBody`. Retry after `Retry-After` when the response has one, else with backoff.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the response has one."
              }
            }
          }
        }
      }
    },
    "/v3/routing/validate/suggest": {
      "post": {
        "tags": [
          "Routing"
        ],
        "summary": "Check a suggest request without running it",
        "description": "Checks a `POST /v3/routing/suggest` request without searching. Only the request's validity is judged, not whether the tasks outside `plan` can be placed: a task with no feasible position still passes, and only a malformed request is a 400 (or 403). It runs the checks `POST /v3/routing/suggest` runs before it fetches travel times, and stops there: no travel times are fetched, nothing is searched, no solver slot is taken, and the call is not billed. The body is the body of `POST /v3/routing/suggest`. A valid request returns `{\"valid\": true, \"warnings\": []}`; an invalid one returns the 400 (or 403) the real call would. Not covered, because the real call makes these checks only after it fetches travel times: coordinates that span more than one Maps region (a 400 on the real call), and the `plan` beyond suggest's own rule that it leaves a task to place, which does run here (that its routes and stops name vehicles, shifts, tasks and depots of `problem`, and that it imports; see the plan errors in the errors guide).",
        "operationId": "validate_suggest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              },
              "examples": {
                "minimal": {
                  "summary": "One vehicle, one job in the plan, one job to place, straight-line travel",
                  "value": {
                    "options": {
                      "max_insertions": 3
                    },
                    "plan": {
                      "routes": [
                        {
                          "shift": "mon",
                          "stops": [
                            {
                              "id": "job-1",
                              "type": "job"
                            }
                          ],
                          "vehicle": "v1"
                        }
                      ]
                    },
                    "problem": {
                      "jobs": [
                        {
                          "id": "job-1",
                          "location": [
                            3.725,
                            51.05
                          ],
                          "service_duration_s": 300
                        },
                        {
                          "id": "job-2",
                          "location": [
                            3.71,
                            51.06
                          ],
                          "service_duration_s": 300
                        }
                      ],
                      "travel": {
                        "engine": "straight_line"
                      },
                      "vehicles": [
                        {
                          "id": "v1",
                          "shifts": [
                            {
                              "end": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "from": "2026-07-01T08:00:00+02:00",
                              "id": "mon",
                              "start": {
                                "location": [
                                  3.7174,
                                  51.0543
                                ]
                              },
                              "to": "2026-07-01T17:00:00+02:00"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The request passed every check made before travel times are fetched. `warnings` lists the advisories the real call would return that need no travel data: an `options.time_limit_s` below the 0.1 s floor (`time_limit_raised`), an option the travel engine makes inert, or plan flags evaluate ignores (`no_effect`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. `errors[]` lists what to fix, each entry with a `code` and, when the problem is in the body, a JSON `pointer` to it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "examples": {
                  "several_problems": {
                    "summary": "Two problems reported together",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "actual": 600,
                          "code": "limit_exceeded",
                          "limit": 60,
                          "message": "options.time_limit_s must be <= 60, got 600",
                          "pointer": "/options/time_limit_s"
                        },
                        {
                          "code": "out_of_range",
                          "message": "job 'delivery-2': priority must be >= 1, got 0",
                          "pointer": "/problem/jobs/1/priority"
                        }
                      ],
                      "message": "2 problems in request",
                      "request_id": "req_7f3a2c90d1e4b5a6",
                      "status": "BAD_REQUEST"
                    }
                  },
                  "unknown_field": {
                    "summary": "A misspelt or unknown field",
                    "value": {
                      "code": "invalid_request",
                      "errors": [
                        {
                          "code": "unknown_field",
                          "message": "unknown field `time_limit`, expected one of `max_insertions`, `time_limit_s`, `travel_fallback` at line 1 column 702",
                          "pointer": "/options/time_limit"
                        }
                      ],
                      "message": "unknown field `time_limit`, expected one of `max_insertions`, `time_limit_s`, `travel_fallback` at line 1 column 702",
                      "request_id": "req_2b9d41c07a35e6f8",
                      "status": "BAD_REQUEST"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature that is not enabled and is available on request from Solvice, for example live-traffic travel (`tomtom_real_time`)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "feature_not_enabled",
                  "errors": [],
                  "message": "travel.engine: 'tomtom_real_time' is not enabled; it is available on request from Solvice. Use engine 'tomtom' meanwhile",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "FORBIDDEN"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (10,485,760 bytes), counted after gzip decompression",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "payload_too_large",
                  "errors": [],
                  "message": "Request body exceeds 10485760 bytes",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "PAYLOAD_TOO_LARGE"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is missing or not JSON (`application/json` or `application/*+json`), or the body has a `Content-Encoding` other than `gzip` (the message says which)",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "unsupported_media_type",
                  "errors": [],
                  "message": "Expected request with `Content-Type: application/json`",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "UNSUPPORTED_MEDIA_TYPE"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Returned by the API gateway before the request reaches the solver, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "500": {
            "description": "Server-side error (`code: internal`).",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                },
                "example": {
                  "code": "internal",
                  "errors": [],
                  "message": "internal error",
                  "request_id": "req_7f3a2c90d1e4b5a6",
                  "status": "INTERNAL_SERVER_ERROR"
                }
              }
            }
          },
          "503": {
            "description": "The platform in front of the solver could not take the request. This endpoint takes no solver slot, so the solver itself never answers 503 here; the response is the API gateway's own shape, not the `ErrorBody`. Retry after `Retry-After` when the response has one, else with backoff.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the response has one."
              }
            }
          }
        }
      }
    },
    "/v3/routing/runs": {
      "post": {
        "tags": [
          "Runs"
        ],
        "operationId": "submitRoutingRun",
        "summary": "Submit an async run",
        "description": "Starts a solve in the background and returns at once with `202` and the run. The body is the same as `POST /v3/routing/solve`, except that `options.time_limit_s` may go up to 3600 and `callback` is not supported yet. The request is checked before the run is accepted, so a bad body is a `400` here, not a failed run later.\n\nPoll `GET /v3/routing/runs/{id}` until `status` is `succeeded`, `failed` or `cancelled`, then read the plan from `GET /v3/routing/runs/{id}/result`. At most 10 runs per account are queued or running at once.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Run accepted. It is `queued` until a worker starts it.",
            "headers": {
              "x-request-id": {
                "schema": {
                  "type": "string"
                },
                "description": "The request's `X-Request-Id`, echoed, or a generated `req_…` id."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                },
                "example": {
                  "id": "d28568b1-34cc-4f89-b10b-dc24b26a8275",
                  "status": "queued",
                  "links": {
                    "self": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275",
                    "result": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid: the same `ErrorBody` as `POST /v3/routing/solve`. A `callback` field is `not_supported` at `/callback`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "403": {
            "description": "The request uses a feature this account does not have (`code: feature_not_enabled`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "413": {
            "description": "Request body larger than 10 MiB (`code: payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "415": {
            "description": "Request `Content-Type` is not `application/json` (`code: unsupported_media_type`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, or this account already has 10 queued or running runs (a cancelled run still counts until its worker stops). Returned by the API gateway, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying. `30` when the cap of 10 runs is the cause."
              }
            }
          },
          "503": {
            "description": "The solver or the worker platform could not take the run. Nothing was started; submit again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "Failed to launch routing run",
                  "error": "GATEWAY_ERROR"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the service knows."
              }
            }
          }
        }
      }
    },
    "/v3/routing/runs/{id}": {
      "get": {
        "tags": [
          "Runs"
        ],
        "operationId": "getRoutingRunStatus",
        "summary": "Get the status of a run",
        "description": "Returns the run. A run that was not finished is checked against its worker on every call: if the worker is gone, the run turns `failed` with `worker_lost`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run id returned by `POST /v3/routing/runs`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                },
                "examples": {
                  "running": {
                    "summary": "Running",
                    "value": {
                      "id": "d28568b1-34cc-4f89-b10b-dc24b26a8275",
                      "status": "running",
                      "links": {
                        "self": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275",
                        "result": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result"
                      },
                      "started_at": "2026-10-15T07:40:59Z"
                    }
                  },
                  "succeeded": {
                    "summary": "Succeeded",
                    "value": {
                      "id": "d28568b1-34cc-4f89-b10b-dc24b26a8275",
                      "status": "succeeded",
                      "links": {
                        "self": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275",
                        "result": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result"
                      },
                      "started_at": "2026-10-15T07:40:59Z",
                      "finished_at": "2026-10-15T07:42:01Z",
                      "expires_at": "2027-10-15T07:42:01Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID. Body: `{\"error\": \"Invalid UUID string: …\"}`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "error": "Invalid UUID string: not-a-uuid"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "404": {
            "description": "No run with this id on your account. Runs of other accounts are also `404`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, as on every endpoint. Returned by the API gateway, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "503": {
            "description": "The service cannot take the request right now. Wait for the `Retry-After` header when the response has one, else retry with backoff. Returned by the API gateway, in its own shape.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the service knows."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "Service unavailable",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          }
        }
      }
    },
    "/v3/routing/runs/{id}/result": {
      "get": {
        "tags": [
          "Runs"
        ],
        "operationId": "getRoutingRunResult",
        "summary": "Get the plan of a run",
        "description": "Returns the plan of a `succeeded` run: the same `SolveResponse` that `POST /v3/routing/solve` returns. While the run is `queued` or `running` this is a `409` with `run_not_finished`; a `failed` or `cancelled` run has no plan (`409`, `no_result`).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run id returned by `POST /v3/routing/runs`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SolveResponse"
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID. Body: `{\"error\": \"Invalid UUID string: …\"}`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "error": "Invalid UUID string: not-a-uuid"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "404": {
            "description": "No run with this id on your account. Runs of other accounts are also `404`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          },
          "409": {
            "description": "The run has no plan to return. `message` starts with `run_not_finished` while the run is `queued` or `running`, and with `no_result` when it `failed` or was `cancelled`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "run_not_finished: run d28568b1-34cc-4f89-b10b-dc24b26a8275 is queued",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, as on every endpoint. Returned by the API gateway, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "503": {
            "description": "The service cannot take the request right now. Wait for the `Retry-After` header when the response has one, else retry with backoff. Returned by the API gateway, in its own shape.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the service knows."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "Service unavailable",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          }
        }
      }
    },
    "/v3/routing/runs/{id}/cancel": {
      "post": {
        "tags": [
          "Runs"
        ],
        "operationId": "cancelRoutingRun",
        "summary": "Cancel a run",
        "description": "Cancels a `queued` or `running` run. The answer is the run: `cancelled`, or unchanged when it had already finished (finishing wins a race). Cancelling does not stop the worker, so the run keeps counting toward the limit of 10 queued or running runs until its worker stops, and a cancelled run never serves a plan.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The run id returned by `POST /v3/routing/runs`.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The run, `cancelled`, or in its final state when it had already finished.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                },
                "example": {
                  "id": "d28568b1-34cc-4f89-b10b-dc24b26a8275",
                  "status": "cancelled",
                  "links": {
                    "self": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275",
                    "result": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result"
                  },
                  "finished_at": "2026-10-15T07:41:22Z",
                  "expires_at": "2027-10-15T07:41:22Z"
                }
              }
            }
          },
          "400": {
            "description": "`id` is not a UUID. Body: `{\"error\": \"Invalid UUID string: …\"}`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "error": "Invalid UUID string: not-a-uuid"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key. Returned by the API gateway, so it does not use the `ErrorBody` shape and can have an empty body. Branch on the HTTP status."
          },
          "404": {
            "description": "No run with this id on your account. Runs of other accounts are also `404`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited, as on every endpoint. Returned by the API gateway, so it does not use the `ErrorBody` shape. Wait for the number of seconds in the `Retry-After` header, then retry.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "503": {
            "description": "The service cannot take the request right now. Wait for the `Retry-After` header when the response has one, else retry with backoff. Returned by the API gateway, in its own shape.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying, when the service knows."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                },
                "example": {
                  "message": "Service unavailable",
                  "error": "GATEWAY_ERROR"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AssignmentCost": {
        "type": "object",
        "description": "Absolute price of serving one task on one vehicle.",
        "required": [
          "vehicle",
          "cost"
        ],
        "properties": {
          "cost": {
            "type": "number",
            "format": "double",
            "description": "Cost, in the objective's currency, incurred when this vehicle serves\nthe task. Must be finite and `>= 0`. A vehicle not listed costs `0`.",
            "example": 12.5,
            "maximum": 21474.83647,
            "minimum": 0
          },
          "vehicle": {
            "type": "string",
            "description": "Vehicle id; applies to every shift of that vehicle. An id that matches\nno vehicle, or a vehicle listed twice in one task's\n`assignment_costs`, is rejected with HTTP 400.",
            "example": "v1"
          }
        },
        "additionalProperties": false,
        "example": {
          "cost": 12.5,
          "vehicle": "v1"
        }
      },
      "Break": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/BreakWindowed"
          },
          {
            "$ref": "#/components/schemas/BreakTriggered"
          },
          {
            "$ref": "#/components/schemas/BreakFixed"
          }
        ],
        "description": "A scheduled break within a shift. Tagged by `type`:\n\n- `windowed`: a break of `duration_s` that starts inside its window.\n- `triggered`: a break of `duration_s` taken once drive or duty time\n  passes `threshold_s` (the EU-561 mechanism).\n- `fixed`: a hard off-duty interval from `from` to `to`.\n\nBreaks are injected between stops and appear in the response as `break`\nstops, carrying the break's `id` when it has one.\n\nA `triggered` break always resets its accumulator after a qualifying break:\n`resets_accumulator` does not exist on it. A `windowed` break takes exactly\none `time_window`. Both are taken wherever the vehicle is, so neither has a\n`location`; sending one is an unknown field (HTTP 400, `unknown_field`).\n\nThere is no paid/unpaid cost accounting: a break's duration is never\nseparately priced, and no `paid` field exists on this schema — sending one\nis rejected as an unknown field (HTTP 400, `unknown_field`), like any other extra key.",
        "example": {
          "after": "drive",
          "duration_s": 1800,
          "threshold_s": 14400,
          "type": "triggered"
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "fixed": "#/components/schemas/BreakFixed",
            "triggered": "#/components/schemas/BreakTriggered",
            "windowed": "#/components/schemas/BreakWindowed"
          }
        }
      },
      "BreakFixed": {
        "type": "object",
        "title": "Fixed",
        "description": "Mandatory off-duty interval at a fixed time. No service is scheduled\ninside it, but a drive already under way at `from` continues through\nit and counts in both `travel_s` and `break_s`.",
        "required": [
          "from",
          "to",
          "type"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the break (RFC 3339 instant, UTC offset required)."
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional break id: 1 to 128 characters, unique within the shift.\nEchoed as `id` on the `break` stop that realises this break.",
            "example": "lunch",
            "maxLength": 128,
            "minLength": 1
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "End of the break (RFC 3339 instant, UTC offset required)."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `fixed`.",
            "enum": [
              "fixed"
            ]
          }
        },
        "additionalProperties": false
      },
      "BreakTimeWindow": {
        "type": "object",
        "description": "The window a `windowed` break must start in. Always hard.",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest break start (RFC 3339 instant, UTC offset required)."
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Latest break start (RFC 3339 instant, UTC offset required)."
          }
        },
        "additionalProperties": false,
        "example": {
          "from": "2026-07-01T12:00:00+02:00",
          "to": "2026-07-01T13:30:00+02:00"
        }
      },
      "BreakTriggered": {
        "type": "object",
        "title": "Triggered",
        "description": "A break taken once drive or duty time passes a threshold.",
        "required": [
          "duration_s",
          "after",
          "threshold_s",
          "type"
        ],
        "properties": {
          "after": {
            "$ref": "#/components/schemas/TriggerAfter",
            "description": "What to accumulate: drive time or duty time."
          },
          "duration_s": {
            "type": "integer",
            "format": "int32",
            "description": "Break duration in seconds. Must be `> 0`.",
            "minimum": 1
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional break id: 1 to 128 characters, unique within the shift.\nEchoed as `id` on the `break` stop that realises this break.",
            "example": "lunch",
            "maxLength": 128,
            "minLength": 1
          },
          "threshold_s": {
            "type": "integer",
            "format": "int64",
            "description": "Trigger threshold in seconds (strict `>` — the break fires when the\naccumulator exceeds this). EU 561/2006 drive rule: `16200` (4 h 30).\nMust be `> 0` and at most 2,147,483,647.",
            "example": 14400,
            "maximum": 2147483647,
            "minimum": 1
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `triggered`.",
            "enum": [
              "triggered"
            ]
          }
        },
        "additionalProperties": false
      },
      "BreakWindowed": {
        "type": "object",
        "title": "Windowed",
        "description": "A break that must start inside a time window.",
        "required": [
          "duration_s",
          "time_window",
          "type"
        ],
        "properties": {
          "duration_s": {
            "type": "integer",
            "format": "int32",
            "description": "Break duration in seconds. Must be `> 0`.",
            "minimum": 1
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional break id: 1 to 128 characters, unique within the shift.\nEchoed as `id` on the `break` stop that realises this break.",
            "example": "lunch",
            "maxLength": 128,
            "minLength": 1
          },
          "time_window": {
            "$ref": "#/components/schemas/BreakTimeWindow",
            "description": "The window bounding the break's **start**."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `windowed`.",
            "enum": [
              "windowed"
            ]
          }
        },
        "additionalProperties": false
      },
      "ConstraintCode": {
        "type": "string",
        "description": "The constraint a violation breaks or a reason names: one vocabulary for\n`routes[].violations[].code`, `routes[].stops[].violations[].code` and\n`unassigned[].reasons[].constraint`.\n\nNew values may be added; clients must accept unknown values and handle\nthem generically, for example by showing `message`.\n\nKnown values: `unreachable`, `max_leg_travel`, `required_skills`, `serves_tags`, `capacity`, `time_window`, `eligible_vehicles`, `shift_end`, `max_distance`, `max_route_duration`, `max_stops`, `sequence`, `tag_order`, `shipment`, `break`, `multi_trip`, `unload_before_end`, `same_vehicle`, `same_day`, `same_route`, `compatible_vehicles`, `synchronized`, `time_lag`, `all_or_none`, `period_limit`, `quota`, `max_intake`, `load_compatibility`, `unknown`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "capacity",
        "x-extensible-enum": [
          "unreachable",
          "max_leg_travel",
          "required_skills",
          "serves_tags",
          "capacity",
          "time_window",
          "eligible_vehicles",
          "shift_end",
          "max_distance",
          "max_route_duration",
          "max_stops",
          "sequence",
          "tag_order",
          "shipment",
          "break",
          "multi_trip",
          "unload_before_end",
          "same_vehicle",
          "same_day",
          "same_route",
          "compatible_vehicles",
          "synchronized",
          "time_lag",
          "all_or_none",
          "period_limit",
          "quota",
          "max_intake",
          "load_compatibility",
          "unknown"
        ]
      },
      "Costs": {
        "type": "object",
        "description": "What running a vehicle costs, in the request's currency\n(`objective.currency` is only a label). `objective.costs` prices the fleet\nand `vehicles[].costs` replaces a field for one vehicle; `shifts[].costs`\nis the same without `per_used_vehicle` (schema `ShiftCosts`), and replaces\na field for one shift. Each field resolves on its own: the shift's value,\nelse the vehicle's, else the fleet's, else the default. Nothing is added\non top of a fleet rate, and every field is reported under the same\n`score.components` key at every level. `0` means priced at zero; absent\nmeans inherit.\n\nRates are rounded to the internal grid (1/100 000 of a currency unit per\nsecond or per metre); a nonzero rate too small to represent is rejected.\nEvery value must be finite and `>= 0`.\n\nLateness is not priced here: `objective.per_late_hour` (or a window's own\n`per_late_hour`) is the rate, because it softens a constraint rather than\npricing a resource.",
        "properties": {
          "min_billed_stops": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "The fewest stops a used shift is billed for at `per_stop`: a used\nshift with fewer stops pays `per_stop × min_billed_stops`. Models a\nsubcontractor guaranteed a minimum volume per route. It prices, it\ndoes not force: the solver may still plan fewer stops on a shift, or\nleave a shift unused (it then pays nothing). Default `0`. `0` to\n`20000`. Requires a `per_stop` (set at this or another level) on\nevery shift it applies to, else HTTP 400.",
            "example": 20,
            "maximum": 20000,
            "minimum": 0
          },
          "per_drive_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour of driving, priced on the route's `time.travel_s` (leg travel\ntimes after `speed_factor`) and reported in `score.components.driving`.\nOn top of `per_route_hour`, whose span includes the drive, so a driving\nsecond costs `per_route_hour + per_drive_hour`. Waiting, service and\nbreaks are not charged here. To charge time for driving only, send\n`per_route_hour: 0` with this rate; `per_travel_km` (default `0.20`)\nstill prices the distance, so send `per_travel_km: 0` as well to price\ndriving time alone. Default `0`.",
            "example": 0.0,
            "minimum": 0
          },
          "per_overtime_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour a route finishes past its shift's `to` (possible only with\n`max_overtime_s`), reported in `score.components.overtime`, on top of\n`per_route_hour`. Default `0`: overtime is unpriced.",
            "example": 0.0,
            "minimum": 0
          },
          "per_route": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Flat charge for each used shift (a route with at least one task),\nreported in `score.components.routes`. Default `0`. The higher it is,\nthe more travel the solver accepts to avoid opening another route. It\ncounts shifts, not vehicles: a vehicle that works five days pays it five\ntimes, so it does not prefer one vehicle on two shifts over two vehicles\non one shift each; use `per_used_vehicle` for that.",
            "example": 50.0,
            "maximum": 1000000000,
            "minimum": 0
          },
          "per_route_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour of each route's wall-clock span (travel, service, waiting\nand breaks), reported in `score.components.time`. **Default.** `35`\nat objective level; a vehicle or shift value inherits the fleet value.",
            "example": 35.0,
            "minimum": 0
          },
          "per_stop": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Flat charge for each stop a used shift serves, reported in\n`score.components.stops`. A job is one stop and a shipment two, as\n`limits.max_stops` counts them; start, end, break and reload stops\nare not billed. Adds to `per_route`. A shift that serves nothing pays\nnothing. Default `0`. At most 100000.",
            "example": 2.5,
            "maximum": 100000,
            "minimum": 0
          },
          "per_travel_km": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per kilometre driven, reported in `score.components.distance`.\n**Default.** `0.20` at objective level; a vehicle or shift value\ninherits the fleet value.",
            "example": 0.2,
            "minimum": 0
          },
          "per_used_vehicle": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Flat charge once per vehicle that serves at least one task, however\nmany of its shifts it works. Reported in `score.components.vehicles`.\nAdds to `per_route`: the vehicle's first used shift pays both, later\nshifts only `per_route`. Default `0`. Use it to minimise distinct\nvehicles; use `per_route` to price each working day. Not accepted on\n`shifts[].costs`. When any vehicle has a non-zero rate and any vehicle\nhas several shifts, the request is solved as a whole rather than split into parts, which can make a large request slower.",
            "example": 400.0,
            "maximum": 1000000000,
            "minimum": 0
          },
          "per_wait_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour spent waiting for a time window to open, reported in\n`score.components.waiting`, on top of `per_route_hour` (the span\nincludes the wait). Idle before a windowed break's window opens is\nreported in `wait_s` but not charged here. Default `0`.",
            "example": 0.0,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "per_route": 50.0,
          "per_route_hour": 35.0,
          "per_travel_km": 0.2
        }
      },
      "Depot": {
        "type": "object",
        "description": "A depot: a place a shift starts from, ends at, or reloads at mid-shift,\nreferenced by `id` from `shifts[].start`, `shifts[].end` and\n`shifts[].reloads`. Each depot keeps its own handling time and reload cost.",
        "required": [
          "id",
          "location"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Depot id: 1 to 128 characters, unique across `depots[]`.",
            "example": "gent",
            "maxLength": 128,
            "minLength": 1
          },
          "location": {
            "$ref": "#/components/schemas/Place",
            "description": "Where the depot is."
          },
          "max_intake": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "The most load the depot may receive across the whole request, per\nnamed dimension: a tip site's intake limit. Not per day: it sums every\nshift of every day.\n\nCounted is the load on board on arrival at each reload here (including\na shift's `initial_load` on its first trip and the final tip of\n`unload_before_end`), plus the load on board at the end of a shift\nwhose `end` is this depot (not with `unload_before_end`, which unloads\nat a reload first). A shift's start never counts, and an unused shift\nreceives nothing. A dimension left out is uncapped; `0` means the\ndepot takes none of it. A hard limit: a task that would overfill every\ndepot its trip can tip at stays unassigned (reason `max_intake`).\n\nEach dimension must be one a task or vehicle declares, and some shift\nmust reload here, or end here without `unload_before_end`."
              }
            ],
            "description": "The most load the depot may receive across the whole request, per\nnamed dimension: a tip site's intake limit. Not per day: it sums every\nshift of every day.\n\nCounted is the load on board on arrival at each reload here (including\na shift's `initial_load` on its first trip and the final tip of\n`unload_before_end`), plus the load on board at the end of a shift\nwhose `end` is this depot (not with `unload_before_end`, which unloads\nat a reload first). A shift's start never counts, and an unused shift\nreceives nothing. A dimension left out is uncapped; `0` means the\ndepot takes none of it. A hard limit: a task that would overfill every\ndepot its trip can tip at stays unassigned (reason `max_intake`).\n\nEach dimension must be one a task or vehicle declares, and some shift\nmust reload here, or end here without `unload_before_end`."
          },
          "per_reload": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Money charged once per reload visit, in the objective's currency.\n**Default.** `0`; at most `1e9`. A shift that only starts or ends here\nis not charged.\n\n**When to use.** A reload has a real per-reload price the travel terms\ncannot see — typically the driver labour for the unload itself\n(`service_duration_s` × the hourly rate). Without it, a reload that\nconsumes only *slack* is free in the objective: it adds no route\nduration, so the solver may insert one to displace time that\n`objective.costs.per_wait_hour` would otherwise charge as idle, parking\nthe vehicle at a depot for no capacity benefit.",
            "example": 38.66,
            "maximum": 1000000000,
            "minimum": 0
          },
          "service_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Handling time in seconds per visit: the load before a shift that starts\nhere, the unload after a shift that ends here, and each reload. A shift\nend's own `service_duration_s` overrides it for that end. Default 0.\nThe unload after a shift must finish by that shift's `to` (or\n`to + max_overtime_s`). Not scaled by `service_factor`: this is\ndepot-side handling, not the driver's on-site work rate.",
            "example": 900,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "gent",
          "location": [
            3.7174,
            51.0543
          ],
          "service_duration_s": 900
        }
      },
      "ErrorBody": {
        "type": "object",
        "description": "Error body of every `/v3/routing/*` endpoint.\n\n`status` is the HTTP status as text, `code` says what kind of failure it\nis, `request_id` identifies the request, and `errors` holds one item per\nproblem found in the request. Branch on `code`, and on `errors[].code` for\n400s; the messages are for people.",
        "required": [
          "status",
          "code",
          "message",
          "errors"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ErrorCode",
            "description": "What kind of failure this is. One value per HTTP status class."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestIssue"
            },
            "description": "One entry per problem found in the request. Always present; empty for\nnon-input errors."
          },
          "message": {
            "type": "string",
            "description": "Human-readable summary. With exactly one item it is that item's\nmessage; with several, `\"{n} problems in request\"` (at most 100 items\nare listed, and the message says when the list is cut)."
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `X-Request-Id` of the request (echoed, or generated when absent)."
          },
          "status": {
            "type": "string",
            "description": "The HTTP status as text, e.g. `\"BAD_REQUEST\"` or\n`\"SERVICE_UNAVAILABLE\"`.",
            "example": "BAD_REQUEST"
          }
        },
        "example": {
          "code": "invalid_request",
          "errors": [
            {
              "code": "out_of_range",
              "message": "depot 'gent': service_duration_s must be >= 0, got -60",
              "pointer": "/problem/depots/0/service_duration_s"
            }
          ],
          "message": "depot 'gent': service_duration_s must be >= 0, got -60",
          "request_id": "req_7f3a2c90d1e4b5a6",
          "status": "BAD_REQUEST"
        }
      },
      "ErrorCode": {
        "type": "string",
        "description": "The top-level `code` of an error body: one code per cause, and every\ncause the routing service answers with an error body has one. Branch on\nthe HTTP status first, then on `code`.\n\n| HTTP | `code` | Cause | Retry |\n|------|--------|-------|-------|\n| 400 | `invalid_request` | The request is invalid; `errors[]` lists each problem | No: fix the request |\n| 403 | `feature_not_enabled` | The request uses a feature this account does not have | No |\n| 404 | `not_found` | No operation at this path | No: fix the path |\n| 405 | `method_not_allowed` | The path exists but not with this method; `Allow` lists the ones it takes | No |\n| 413 | `payload_too_large` | The body is larger than 10 MiB after decompression | No |\n| 415 | `unsupported_media_type` | `Content-Type` is not JSON, or `Content-Encoding` is not gzip | No |\n| 500 | `internal` | A fault on the server side | Once, then contact support with `request_id` |\n| 502 | `travel_provider_error` | Travel times and distances could not be fetched (`travel_fallback: \"fail\"` only) | Yes, with backoff |\n| 503 | `overloaded` | Every solver slot is busy, or the wait for one timed out | Yes, after `Retry-After` |\n| 503 | `travel_provider_unavailable` | Travel lookups are suspended after repeated failures (`travel_fallback: \"fail\"` only) | Yes, after `Retry-After` |\n\nA 401 and a 429 come from the API gateway, without this body; a 429\ncarries `Retry-After`.\n\nKnown values: `invalid_request`, `feature_not_enabled`, `not_found`, `method_not_allowed`, `payload_too_large`, `unsupported_media_type`, `internal`, `travel_provider_error`, `overloaded`, `travel_provider_unavailable`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "x-extensible-enum": [
          "invalid_request",
          "feature_not_enabled",
          "not_found",
          "method_not_allowed",
          "payload_too_large",
          "unsupported_media_type",
          "internal",
          "travel_provider_error",
          "overloaded",
          "travel_provider_unavailable"
        ]
      },
      "ErrorItemCode": {
        "type": "string",
        "description": "The `code` of one `errors[]` item. Clients should accept values they do\nnot know yet.\n\nKnown values: `invalid_json`, `invalid_type`, `unknown_field`, `missing_field`, `invalid_value`, `not_supported`, `out_of_range`, `duplicate_id`, `unknown_reference`, `conflicting_fields`, `limit_exceeded`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "x-extensible-enum": [
          "invalid_json",
          "invalid_type",
          "unknown_field",
          "missing_field",
          "invalid_value",
          "not_supported",
          "out_of_range",
          "duplicate_id",
          "unknown_reference",
          "conflicting_fields",
          "limit_exceeded"
        ]
      },
      "EvaluateRequest": {
        "type": "object",
        "description": "Request body for `POST /v3/routing/evaluate`.\n\nScores `plan` against `problem` without running the optimizer: objective\ntotals, timing, loads and constraint violations. Tasks absent from every\nroute are reported as unassigned. A solve response's `plan` goes in as it\nstands.",
        "required": [
          "problem",
          "plan"
        ],
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/Plan",
            "description": "The plan to score."
          },
          "problem": {
            "$ref": "#/components/schemas/Problem",
            "description": "Problem definition — identical to `POST /v3/routing/solve`."
          }
        },
        "additionalProperties": false,
        "example": {
          "plan": {
            "routes": [
              {
                "shift": "mon",
                "stops": [
                  {
                    "id": "job-1",
                    "type": "job"
                  }
                ],
                "vehicle": "v1"
              }
            ]
          },
          "problem": {
            "jobs": [
              {
                "id": "job-1",
                "location": [
                  3.725,
                  51.05
                ],
                "pickup_load": {
                  "weight": 10
                },
                "service_duration_s": 300
              }
            ],
            "vehicles": [
              {
                "capacity": {
                  "weight": 500
                },
                "id": "v1",
                "shifts": [
                  {
                    "end": {
                      "location": [
                        3.7174,
                        51.0543
                      ]
                    },
                    "from": "2026-07-01T08:00:00+02:00",
                    "id": "mon",
                    "start": {
                      "location": [
                        3.7174,
                        51.0543
                      ]
                    },
                    "to": "2026-07-01T17:00:00+02:00"
                  }
                ]
              }
            ]
          }
        }
      },
      "Grouping": {
        "type": "object",
        "description": "Keep geographically clustered tasks consecutive in a route.\n\nTwo tasks are in the same **group** when they lie within `radius_m` of\neach other. The solver adds `per_entry` to the objective each time a\nroute enters a group from a job outside it, the first entry included;\nentering from the shift's start or from a reload is free. Keeping each\ngroup in one visit minimises how often a route comes back to an area it\nalready served. Presence of this object enables the feature; omit\nit to disable.",
        "required": [
          "per_entry"
        ],
        "properties": {
          "distance_metric": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/GroupingDistance",
                "description": "How neighbour distance is measured. Default `\"straight_line\"`."
              }
            ],
            "description": "How neighbour distance is measured. Default `\"straight_line\"`.",
            "default": "straight_line"
          },
          "per_entry": {
            "type": "number",
            "format": "double",
            "description": "Cost added to the objective on every entry into a group from a job\noutside it (a job that is not within `radius_m` of the entered one),\nthe first entry included, in the objective's currency. Entry from the\nshift's start or from a reload is free. At most 1000 currency units: a\nlarger value is rejected with HTTP 400. Higher keeps clusters together\nmore aggressively at the expense of total travel.",
            "example": 0.5,
            "maximum": 1000,
            "minimum": 0
          },
          "radius_m": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Radius defining a group, in metres. Default `180`. Must be `> 0`.",
            "default": 180,
            "example": 180,
            "minimum": 1
          }
        },
        "additionalProperties": false,
        "example": {
          "distance_metric": "straight_line",
          "per_entry": 0.5,
          "radius_m": 180
        }
      },
      "GroupingDistance": {
        "type": "string",
        "description": "How neighbour distance is measured for `objective.grouping`.",
        "enum": [
          "straight_line",
          "road"
        ],
        "example": "straight_line"
      },
      "InsertionDelta": {
        "type": "object",
        "description": "How an option changes the plan: the change in its score's `cost` and in\nits routes' summed `distance_m` and `time.travel_s`. Equal to the difference\nbetween two `/evaluate` calls, with and without the option (`cost` up to\nfloating-point rounding).",
        "required": [
          "cost",
          "distance_m",
          "travel_s"
        ],
        "properties": {
          "cost": {
            "type": "number",
            "format": "double",
            "description": "Change in the score's `cost`, in the request's currency. Negative when\nserving a task saves more `drop_cost` than it costs to route.",
            "example": 12.4
          },
          "distance_m": {
            "type": "integer",
            "format": "int64",
            "description": "Change in the summed route `distance_m`, in metres.",
            "example": 2400
          },
          "travel_s": {
            "type": "integer",
            "format": "int64",
            "description": "Change in the summed route `time.travel_s` (driving time only), in\nseconds.",
            "example": 240
          }
        },
        "example": {
          "cost": 12.4,
          "distance_m": 2400,
          "travel_s": 240
        }
      },
      "InsertionOption": {
        "type": "object",
        "description": "One feasible way to place the whole unit.",
        "required": [
          "delta",
          "placements",
          "routes"
        ],
        "properties": {
          "delta": {
            "$ref": "#/components/schemas/InsertionDelta",
            "description": "What the option changes: `plan` with `routes` swapped in, minus `plan`."
          },
          "interchangeable_vehicles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ShiftRef"
            },
            "description": "Other idle vehicles, each on its own shift, that give the same `delta`\nonce `vehicle` and `shift` are swapped for theirs in `placements` and\n`routes`. Present only when the option opens a vehicle with no stops\nin `plan`. Not guaranteed exhaustive."
          },
          "placements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Placement"
            },
            "description": "Every stop the option adds, in route order."
          },
          "routes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanRoute"
            },
            "description": "Every plan route the option changes, as it reads with the option in:\nthe request's route (its `locked_count` kept), or a new one, with the\nplacements inserted. Replace the routes of `plan` with the same\n`vehicle` and `shift` by these to get the plan `delta` scores."
          }
        },
        "example": {
          "delta": {
            "cost": 12.4,
            "distance_m": 2400,
            "travel_s": 240
          },
          "placements": [
            {
              "arrival": "2026-07-01T09:30:00+02:00",
              "id": "job-2",
              "latest_arrival": "2026-07-01T10:15:00+02:00",
              "service_start": "2026-07-01T09:30:00+02:00",
              "shift": "mon",
              "type": "job",
              "vehicle": "v1"
            }
          ],
          "routes": [
            {
              "shift": "mon",
              "stops": [
                {
                  "id": "job-1",
                  "type": "job"
                },
                {
                  "id": "job-2",
                  "type": "job"
                }
              ],
              "vehicle": "v1"
            }
          ]
        }
      },
      "Job": {
        "type": "object",
        "description": "A single-stop visit: one location served once (the `jobs[]` entry type).\nFor a pickup bound to a delivery on the same vehicle, use `shipments[]`.",
        "required": [
          "id"
        ],
        "properties": {
          "assignment_costs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/AssignmentCost"
            },
            "description": "Absolute price of serving this task on a given vehicle, in the\nobjective's currency. Charged once, when that vehicle (on any of its\nshifts) serves the task; unlisted vehicles cost nothing. Unlike\n`preferences`, which charges the vehicles that did NOT get the task,\nthis prices the vehicle that did, so a task rated badly everywhere is\nthe first one dropped when capacity runs out. It lives in the cost tier,\nbelow `priority`, and adds to `preferences`, `drop_cost` and travel.\nA request that sets it is solved as a whole rather than split into parts, which can make a large request slower."
          },
          "break_interruptible": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether a break may pause this job's service. With `true`, a `fixed`\nbreak, a `windowed` break or a duty-`triggered` break that falls\ninside the service pauses it: the work resumes when the break ends,\nthe job departs the break's length later, and the stop reports the\npaused seconds in `break_s`. A drive-`triggered` break never pauses a\njob (it counts driving time only). Default `false`: the whole service\nmoves after the break, or the break is taken before the job starts, or,\nfor a `windowed` break whose window opens during the job, after it ends\nwhen the break can still start by the window's close.",
            "example": true
          },
          "delivery_load": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Quantity delivered at this visit: comes off the vehicle here, having\nbeen loaded at a depot. Direction is carried by the field itself, never\nby sign — `delivery_load` values are non-negative magnitudes, like `pickup_load`.\n\n**When to use.** Goods loaded at the depot and dropped at the\ncustomer; for a pickup bound to a delivery at another address, use\n`shipments[]`. Unlike a shipment, nothing is picked up for it at another stop: the\ngoods are assumed already aboard from a depot, so the vehicle departs\nits trip carrying the sum of the trip's `delivery_load` quantities.\n\nAbsent or empty means no delivery at this visit."
              }
            ],
            "description": "Quantity delivered at this visit: comes off the vehicle here, having\nbeen loaded at a depot. Direction is carried by the field itself, never\nby sign — `delivery_load` values are non-negative magnitudes, like `pickup_load`.\n\n**When to use.** Goods loaded at the depot and dropped at the\ncustomer; for a pickup bound to a delivery at another address, use\n`shipments[]`. Unlike a shipment, nothing is picked up for it at another stop: the\ngoods are assumed already aboard from a depot, so the vehicle departs\nits trip carrying the sum of the trip's `delivery_load` quantities.\n\nAbsent or empty means no delivery at this visit."
          },
          "drop_cost": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Drop **price** — what leaving this task unserved costs you, in the same\ncurrency as `objective.costs`, and the only way to make a task\ndroppable. **Default.** Absent: the task must be served.\n\n**Pitfall.** This is money, not a priority: it enters the same cost the\nsolver minimises, so the task is served only while serving it costs\nless than dropping it. A task dropped for its price is listed in\n`unassigned[]` with `category: \"priced_out\"`. Drop costs the plan chose\nto pay are reported in `score.components.drop_costs` and summed into\n`score.cost`.\n\nOn a shipment the drop cost applies to the pair, charged once.\n\nMust be finite, `>= 0` and at most `1e9`; combined with `priority` it\nis rejected with HTTP 400 (`conflicting_fields`). Also rejected with\nHTTP 400 (`not_supported`) while a positive `objective.per_delay_workday` is set,\nsince a droppable task could be dropped to avoid its delay charge.",
            "example": 25.0,
            "maximum": 1000000000,
            "minimum": 0
          },
          "eligible_vehicles": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/VehicleEligibility",
                "description": "Hard vehicle allow/exclude. A request may use at most 256 distinct\npermitted-vehicle sets (after resolving `allowed`/`excluded`) across\nall jobs and shipments (HTTP 400 `limit_exceeded` beyond that)."
              }
            ],
            "description": "Hard vehicle allow/exclude. A request may use at most 256 distinct\npermitted-vehicle sets (after resolving `allowed`/`excluded`) across\nall jobs and shipments (HTTP 400 `limit_exceeded` beyond that)."
          },
          "id": {
            "type": "string",
            "description": "Job id: 1 to 128 characters, unique across `jobs` + `shipments`.",
            "example": "job-1",
            "maxLength": 128,
            "minLength": 1
          },
          "location": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Place",
                "description": "Where this visit happens. **Pitfall.** The coordinate is\n`[longitude, latitude]`: a pair sent as `[latitude, longitude]` comes\nback unassigned with `unreachable`, or is a 400 when the swapped\ncoordinates span more than one region. Omit for a \"virtual\"\n(location-less) job:\nit still has service duration, time windows, load, and skills, but\nrequires no travel — the vehicle's position doesn't change when it\nserves one. Virtual and located jobs may be mixed freely in the same\nrequest and route. A virtual job's stop in the solution response\nreports the resolved location of its nearest real (located)\nneighbor in the route — the predecessor when there is one, otherwise\nthe successor — so it is `null` only on a route that has no located\nstop at all (an all-virtual route on an open-start/open-end shift).\nA shipment's legs still require a `location`."
              }
            ],
            "description": "Where this visit happens. **Pitfall.** The coordinate is\n`[longitude, latitude]`: a pair sent as `[latitude, longitude]` comes\nback unassigned with `unreachable`, or is a 400 when the swapped\ncoordinates span more than one region. Omit for a \"virtual\"\n(location-less) job:\nit still has service duration, time windows, load, and skills, but\nrequires no travel — the vehicle's position doesn't change when it\nserves one. Virtual and located jobs may be mixed freely in the same\nrequest and route. A virtual job's stop in the solution response\nreports the resolved location of its nearest real (located)\nneighbor in the route — the predecessor when there is one, otherwise\nthe successor — so it is `null` only on a route that has no located\nstop at all (an all-virtual route on an open-start/open-end shift).\nA shipment's legs still require a `location`."
          },
          "pickup_load": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Quantity picked up at this visit: goes onto the vehicle here and stays\naboard until the route ends or reloads. Non-negative magnitudes per\nnamed dimension. A swap that collects one quantity and drops off\nanother at the same address is one job with both `pickup_load` and\n`delivery_load`."
              }
            ],
            "description": "Quantity picked up at this visit: goes onto the vehicle here and stays\naboard until the route ends or reloads. Non-negative magnitudes per\nnamed dimension. A swap that collects one quantity and drops off\nanother at the same address is one job with both `pickup_load` and\n`delivery_load`."
          },
          "preferences": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/VehiclePreference"
            },
            "description": "Soft vehicle affinity preferences, priced. Each entry is independent:\na job listing several preferred vehicles it doesn't get pays each\none's `violation_cost` (compounding, the same rule as a vehicle's\n`preferred_tags`)."
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Importance of a must-serve task when not all of them fit: the solver\nmaximises the summed `priority` of served tasks before any cost. `1` to\n`100000000000000` (1e14). **Default.** `1`: every task counts the same,\nso the solver serves as many as possible. **Pitfall.** A rank, not\nmoney: it never makes a task droppable; use `drop_cost` for that. Both\nset is a 400. To rank several goals at once, pack them into one value\n(see the scoring guide).",
            "example": 3,
            "maximum": 100000000000000,
            "minimum": 1
          },
          "required_skills": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/SkillRequirement"
            },
            "description": "Hard skill requirements — the assigned vehicle must provide every one,\nat or above each requirement's `min_level`. A request may use at most\n256 distinct `(name, min_level)` pairs across all jobs and shipments\n(HTTP 400 `limit_exceeded` beyond that)."
          },
          "service_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "On-site service time paid per job (seconds).\n\nThis is the nominal figure. The serving vehicle's `service_factor`\nscales it — the time actually scheduled is\n`service_duration_s / service_factor` — so the solution's\n`stops[].service_s` may differ from what you sent here. Default `0`;\na negative value is rejected with HTTP 400.",
            "example": 300,
            "minimum": 0
          },
          "service_factors": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/ServiceFactor"
            },
            "description": "Per-vehicle work-rate factors for this task's `service_duration_s`,\nwhich is DIVIDED by the factor (above `1` = faster). Each multiplies\nthe serving vehicle's rate (the shift's `service_factor` if set, else\nthe vehicle's): effective service time = `service_duration_s /\n(shift_or_vehicle_factor * factor)`. On a shipment the factor scales\nboth legs. A vehicle not listed works at its own rate."
          },
          "setup_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Setup time paid once on arrival at a new location (seconds),\ndistinct from `service_duration_s`. Skipped when the immediate real\npredecessor in the route already sits at this location — co-located\nstops share one setup.\n\nNot scaled by the vehicle's `service_factor`: setup is fixed arrival\noverhead (parking, walking to the door), not the work itself.\nDefault `0`; a negative value is rejected with HTTP 400.",
            "example": 60,
            "minimum": 0
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Free-form task labels (zones/territories, relation labels).\nUsed for `tag`/relation resolution and, when a shift scopes itself via\n`serves_tags` (hard ANY-overlap) or a vehicle prices them via\n`preferred_tags` (soft), for tag matching. ANY-overlap — contrast with\n`required_skills`, which requires ALL. Not capability matching on its own.\nA request may carry at most 256 distinct tags across all jobs and\nshipments (HTTP 400 `limit_exceeded` beyond that); vehicle-side tag\nlists do not count."
          },
          "target": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Target",
                "description": "Soft target for this task, measured at its arrival (default) or\ndeparture. On a shipment it is measured on the **delivery** leg and\ncannot be combined with `delivery.target` (HTTP 400\n`conflicting_fields`); `pickup.target` adds a separate target on the\npickup leg."
              }
            ],
            "description": "Soft target for this task, measured at its arrival (default) or\ndeparture. On a shipment it is measured on the **delivery** leg and\ncannot be combined with `delivery.target` (HTTP 400\n`conflicting_fields`); `pickup.target` adds a separate target on the\npickup leg."
          },
          "time_windows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/TimeWindow"
            },
            "description": "Time windows for this visit."
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "job-1",
          "location": [
            3.725,
            51.05
          ],
          "pickup_load": {
            "weight": 20
          },
          "required_skills": [
            {
              "name": "fridge"
            }
          ],
          "service_duration_s": 300,
          "time_windows": [
            {
              "from": "2026-07-01T09:00:00+02:00",
              "to": "2026-07-01T12:00:00+02:00"
            }
          ]
        }
      },
      "MatrixEngine": {
        "type": "string",
        "description": "Which data prices travel times and distances. Omitted, it follows\n`travel.departure_time`: `osm` without one, `tomtom` with one.\n\n- `tomtom`: TomTom historical-typical traffic at the departure time, or at\n  the moment of the request without one.\n- `osm`: OpenStreetMap free-flow times. No traffic, so\n  `travel.departure_time` is rejected with 400.\n- `tomtom_real_time`: TomTom live traffic at the moment of the request.\n  Available on request from Solvice; until then, a request that sets\n  it and passes every other check is rejected with 403\n  `feature_not_enabled`.\n- `straight_line`: great-circle distance at `travel.speed_kmh`, no road\n  network. `travel.departure_time`, `options.polyline` and any vehicle\n  `profile` other than `car` are rejected with 400.",
        "enum": [
          "tomtom",
          "osm",
          "tomtom_real_time",
          "straight_line"
        ],
        "example": "osm"
      },
      "Objective": {
        "type": "object",
        "description": "Top-level objective configuration.\n\nPlans are compared in a fixed order: first **serve the required tasks**\n(the summed `priority` of the required tasks left unassigned is\nminimised), then **minimise cost** — the `costs` rates plus every priced\npreference, reported as `score.cost`. There is no separate vehicle-count\nstep: to use fewer routes, price them with `costs.per_route`\n(per used shift); to use fewer distinct vehicles when they work several\nshifts, price them with `costs.per_used_vehicle` (once per vehicle).",
        "properties": {
          "costs": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Costs",
                "description": "Fleet cost rates: the default for every vehicle and shift that does\nnot set its own. See the `Costs` schema."
              }
            ],
            "description": "Fleet cost rates: the default for every vehicle and shift that does\nnot set its own. See the `Costs` schema."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Currency label (ISO 4217, e.g. `EUR`) for every amount in the request\nand in `score`. Informational: echoed as `score.currency`, it never\nconverts anything.",
            "example": "EUR"
          },
          "grouping": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Grouping",
                "description": "Job-proximity cluster cohesion. See the `Grouping` schema."
              }
            ],
            "description": "Job-proximity cluster cohesion. See the `Grouping` schema."
          },
          "per_delay_workday": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "ASAP scheduling: money charged for each served task per workday its\nshift lies after the earliest workday in the request, in the request's\ncurrency. A workday is a distinct calendar date, in the shift's own UTC\noffset, on which at least one shift starts; shifts on one date share a\nrank, and a date with no shift adds none. Unserved tasks pay nothing;\nthe charge never outranks `priority` and cannot be combined with\n`drop_cost`. Absent or `0` = off; a single-date request is charged\nnothing. Like `assignment_costs`, a request that sets it, even on one\ndate, is solved as a whole rather than split into parts. Reported as `score.components.delay`. A positive\nrate below `0.00001` is rejected, as is a rate whose total over the\nlater workdays exceeds `21474.83647` (`out_of_range`).",
            "example": 5.0,
            "minimum": 0
          },
          "per_late_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Cost per hour of lateness: the default rate for every task window\nthat does not carry its own `time_windows[].per_late_hour`.\n**Default.** Omitted: every window is hard. **Pitfall.** An explicit\n`0.0` is rejected as ambiguous (free lateness and hard windows read\nopposite ways, and lateness is never free). There is no earliness\nrate. It prices task windows only: a shift's `to` (plus\n`max_overtime_s` when set) stays a hard limit.\nSetting it `> 0` alongside a nonzero `time_windows[].choice_cost` anywhere in\nthe request is rejected with HTTP 400.",
            "example": 60.0,
            "minimum": 0.0006
          },
          "workload_share": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/WorkloadShare",
                "description": "Spreads work across vehicles. See the `WorkloadShare` schema."
              }
            ],
            "description": "Spreads work across vehicles. See the `WorkloadShare` schema."
          }
        },
        "additionalProperties": false,
        "example": {
          "costs": {
            "per_route_hour": 35.0,
            "per_travel_km": 0.2
          },
          "currency": "EUR"
        }
      },
      "PeriodEvery": {
        "type": "string",
        "description": "The recurrence of a period limit (`limits.periods[].every`).",
        "enum": [
          "day",
          "week"
        ]
      },
      "PeriodLimit": {
        "type": "object",
        "description": "A cap on a vehicle's totals across every shift that starts in one period.\nSet exactly one of `every`, or `from` and `to`; and at least one maximum.",
        "properties": {
          "every": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PeriodEvery",
                "description": "A recurring period: every `day`, or every `week` (weeks start Monday)."
              }
            ],
            "description": "A recurring period: every `day`, or every `week` (weeks start Monday)."
          },
          "from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Start of one explicit period (RFC 3339, UTC offset required), with `to`. The window must\nhold at least one of the vehicle's shift starts; a period inside one\nshift is not supported.",
            "example": "2026-10-05T00:00:00+02:00"
          },
          "max_distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard cap on the summed distance driven, in metres. Must be `>= 0`.",
            "example": 900000,
            "minimum": 0
          },
          "max_route_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard cap on the summed route span of the period's shifts, measured as a\nshift's `max_route_duration_s` is, in seconds. An unused shift adds\nnothing. Must be `>= 0`.",
            "example": 144000,
            "minimum": 0
          },
          "max_stops": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "Hard cap on served stops across the period's shifts; a job counts as\none stop. Start, end, break and reload stops in `routes[].stops` do not\ncount; a shipment counts as two stops.",
            "example": 40,
            "minimum": 0
          },
          "to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "End of one explicit period (RFC 3339, UTC offset required, exclusive), with `from`.",
            "example": "2026-10-12T00:00:00+02:00"
          }
        },
        "additionalProperties": false,
        "example": {
          "every": "week",
          "max_route_duration_s": 144000,
          "max_stops": 40
        },
        "oneOf": [
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "every": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "every"
                  ]
                },
                {
                  "not": {
                    "properties": {
                      "from": {
                        "type": "null"
                      }
                    },
                    "required": [
                      "from"
                    ]
                  },
                  "required": [
                    "from"
                  ]
                },
                {
                  "not": {
                    "properties": {
                      "to": {
                        "type": "null"
                      }
                    },
                    "required": [
                      "to"
                    ]
                  },
                  "required": [
                    "to"
                  ]
                }
              ]
            },
            "required": [
              "every"
            ]
          },
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "from": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "from"
                  ]
                },
                {
                  "properties": {
                    "to": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "to"
                  ]
                },
                {
                  "not": {
                    "properties": {
                      "every": {
                        "type": "null"
                      }
                    },
                    "required": [
                      "every"
                    ]
                  },
                  "required": [
                    "every"
                  ]
                }
              ]
            },
            "required": [
              "from",
              "to"
            ]
          }
        ]
      },
      "Place": {
        "type": "array",
        "items": {
          "type": "number",
          "format": "double"
        },
        "description": "A place: a coordinate `[longitude, latitude]` in GeoJSON order — exactly two numbers. Tasks at the same coordinate are treated as one location. Longitude must lie in `[-180, 180]` and latitude in `[-90, 90]` (HTTP 400 `out_of_range` otherwise), and `[0, 0]` is rejected with HTTP 400 `invalid_value` as a missing-GPS placeholder.",
        "examples": [
          [
            3.725,
            51.05
          ]
        ],
        "maxItems": 2,
        "minItems": 2
      },
      "Placement": {
        "type": "object",
        "description": "One stop an option adds: the plan stop, the plan route it goes into and\nwhen it is reached.",
        "required": [
          "type",
          "id",
          "vehicle",
          "shift",
          "arrival",
          "service_start",
          "latest_arrival"
        ],
        "properties": {
          "arrival": {
            "type": "string",
            "format": "date-time",
            "description": "Arrival at this stop (RFC 3339), in the UTC offset of `shift`'s\n`from` (`Z` when that `from` is UTC or has no offset), as on routes.",
            "example": "2026-07-01T09:30:00+02:00"
          },
          "id": {
            "type": "string",
            "description": "The plan stop's `id`: the job id, or the shipment leg's stop id."
          },
          "latest_arrival": {
            "type": "string",
            "format": "date-time",
            "description": "Latest arrival that still keeps the rest of the route feasible\n(RFC 3339, in the offset of `arrival`) — the smaller of the task's own time-window latest and\nthe route's forward slack here. Under priced lateness it may be\n**earlier** than `arrival`. For a `synchronized` or `time_lag` member it\nis at most `arrival` plus the wait before `service_start`: arriving\nlater would move the start its partners are booked to meet.",
            "example": "2026-07-01T10:15:00+02:00"
          },
          "service_start": {
            "type": "string",
            "format": "date-time",
            "description": "Service start (RFC 3339, in the offset of `arrival`): `arrival` plus\nany wait for the time window or a break, and for a `synchronized` or\n`time_lag` member the hold for its partners, as `service_start` on the\nroute stop. With the default `on: service_start`, the members of a\ncrew start here within the relation's `max_spread_s`: the booking time\n(`on: departure` aligns their ends instead; a `time_lag` keeps its lag).",
            "example": "2026-07-01T09:30:00+02:00"
          },
          "shift": {
            "type": "string",
            "description": "Shift of that plan route."
          },
          "type": {
            "$ref": "#/components/schemas/PlanStopType",
            "description": "The plan stop's `type`: `job`, `pickup` or `delivery` (never `reload`:\nsuggest does not open reload trips)."
          },
          "vehicle": {
            "type": "string",
            "description": "Vehicle of the plan route the stop goes into."
          }
        },
        "example": {
          "arrival": "2026-07-01T09:30:00+02:00",
          "id": "s1:pickup",
          "latest_arrival": "2026-07-01T10:15:00+02:00",
          "service_start": "2026-07-01T09:30:00+02:00",
          "shift": "mon",
          "type": "pickup",
          "vehicle": "v1"
        }
      },
      "Plan": {
        "type": "object",
        "description": "A plan: which stops each vehicle shift serves, in order. A result's `plan`\nhas exactly this shape and goes back into evaluate, suggest or a\nwarm-started solve unchanged.",
        "required": [
          "routes"
        ],
        "properties": {
          "routes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanRoute"
            },
            "description": "One entry per vehicle shift that serves something."
          }
        },
        "additionalProperties": false
      },
      "PlanRoute": {
        "type": "object",
        "description": "One vehicle shift's route: every trip of the shift, split by `reload` stops.",
        "required": [
          "vehicle",
          "shift",
          "stops"
        ],
        "properties": {
          "locked_count": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "On solve, the first `locked_count` stops stay where they are (already\ndispatched). Counts every listed stop. Cannot be combined with a\n`reload` stop, and must not exceed the route's stop count — both are\nvalidated on every endpoint that takes a plan. Otherwise inert on\nevaluate. On suggest, no insertion lands before them.",
            "example": 1,
            "minimum": 0
          },
          "shift": {
            "type": "string",
            "description": "Shift id, within that vehicle."
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PlanStop"
            },
            "description": "Stops in visiting order."
          },
          "vehicle": {
            "type": "string",
            "description": "Vehicle id."
          }
        },
        "additionalProperties": false,
        "example": {
          "shift": "mon",
          "stops": [
            {
              "id": "boiler-17",
              "type": "job"
            }
          ],
          "vehicle": "van-3"
        }
      },
      "PlanStop": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PlanStopJob"
          },
          {
            "$ref": "#/components/schemas/PlanStopPickup"
          },
          {
            "$ref": "#/components/schemas/PlanStopDelivery"
          },
          {
            "$ref": "#/components/schemas/PlanStopReload"
          }
        ],
        "description": "One stop of a plan route. Start, end and breaks are placed by the solver\nand are not listed.",
        "example": {
          "id": "parts-9:pickup",
          "type": "pickup"
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "delivery": "#/components/schemas/PlanStopDelivery",
            "job": "#/components/schemas/PlanStopJob",
            "pickup": "#/components/schemas/PlanStopPickup",
            "reload": "#/components/schemas/PlanStopReload"
          }
        }
      },
      "PlanStopDelivery": {
        "type": "object",
        "title": "PlanStopDelivery",
        "description": "A shipment's delivery leg.",
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The leg's stop id: its own `id`, else `{shipment}:delivery`.",
            "example": "parts-9:delivery"
          },
          "pinned": {
            "type": "boolean",
            "description": "Pinned as on a job; pinning one leg pins both."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `delivery`.",
            "enum": [
              "delivery"
            ]
          }
        },
        "additionalProperties": false
      },
      "PlanStopJob": {
        "type": "object",
        "title": "PlanStopJob",
        "description": "A job, by its id.",
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Job id.",
            "example": "boiler-17"
          },
          "pinned": {
            "type": "boolean",
            "description": "On solve, pins the vehicle, not the position: the stop stays on the\nvehicle of the route it sits in (any shift of that vehicle, unless it\nbelongs to a `same_day` or `same_route` group) and the search never\nremoves it, but may still reorder it within the route. Works\nanywhere in a route, unlike the prefix `locked_count`. Judged with\nthe plan's movable (unpinned, unlocked) stops out of its way; a pinned\njob (not a shipment leg) that does not fit where it is listed is\ntried on every shift of the vehicle. Outside a `locked_count` prefix\n(a shipment leg whose other leg is inside counts as inside), never a\n400: a stop late for a window with `per_late_hour` is served\nlate; one that still cannot be served on its vehicle is in\n`unassigned[]`, never on another vehicle, its reasons naming what\nrefuses it beside the other pinned and locked stops (`shift_end`,\n`time_window` when its window cannot be met there, as when it\ncollides with another, `capacity`, `eligible_vehicles`, …).\nOf two stops a `same_vehicle`, `same_day` or `same_route` group\nsplits, a locked one stays, else the pin listed first in the request\n(`jobs`, then `shipments`);\nthe other pin is unassigned for that relation, and a movable member\nis taken off the plan for repair. Pinned `synchronized`/`time_lag`\nmembers that cannot meet are all unassigned for that relation, except\na locked one, which stays; the search may serve one again alone\nunless `all_or_none` holds them together. Accepted on evaluate and\nsuggest, where it is inert. A solve or evaluate result's `plan` never\ncarries it; suggest's\n`insertions[].routes` keep it on purpose, so swapping them back into\n`plan` keeps the pins."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `job`.",
            "enum": [
              "job"
            ]
          }
        },
        "additionalProperties": false
      },
      "PlanStopPickup": {
        "type": "object",
        "title": "PlanStopPickup",
        "description": "A shipment's pickup leg.",
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The leg's stop id: its own `id`, else `{shipment}:pickup`.",
            "example": "parts-9:pickup"
          },
          "pinned": {
            "type": "boolean",
            "description": "Pinned as on a job; pinning one leg pins both."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `pickup`.",
            "enum": [
              "pickup"
            ]
          }
        },
        "additionalProperties": false
      },
      "PlanStopReload": {
        "type": "object",
        "title": "PlanStopReload",
        "description": "A reload at a depot: the next trip starts there. It sits between two\ntask stops, or first on a shift with a non-zero `initial_load`: the unload\nbefore the first job.",
        "required": [
          "depot",
          "type"
        ],
        "properties": {
          "depot": {
            "type": "string",
            "description": "A depot id from the shift's `reloads`.",
            "example": "gent"
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `reload`.",
            "enum": [
              "reload"
            ]
          }
        },
        "additionalProperties": false
      },
      "PlanStopType": {
        "type": "string",
        "description": "The `type` of a plan stop. A closed set: a new plan stop type ships only\nwith a request field that opts into it, so a client that does not send\nthat field never receives one.",
        "enum": [
          "job",
          "pickup",
          "delivery",
          "reload"
        ]
      },
      "PolylineDetail": {
        "type": "string",
        "description": "How much road detail `routes[].polyline` carries.\n\nThis is the knob that decides whether a drawn route follows the roads or\ncuts corners — **not** the polyline encoding precision, which is fixed at 5\nand is a sub-metre concern. Measured on a three-stop, 150 km route:\n\n| detail | shape points | geometry bytes | added latency |\n|--------|--------------|----------------|---------------|\n| `simplified` | 34 | ~200 | ~0 |\n| `full` | 1,728 | ~5,300 | ~0 (inside run-to-run noise) |\n\nPrefer `full` unless response size is the binding constraint: the extra\ndetail is nearly free in time, and `simplified` is what makes a route look\nlike straight lines between stops.",
        "enum": [
          "simplified",
          "full"
        ],
        "example": "full"
      },
      "Problem": {
        "type": "object",
        "description": "The problem part of every V3 request body.",
        "required": [
          "vehicles"
        ],
        "properties": {
          "depots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Depot"
            },
            "description": "Depots that shifts start from, end at, or reload at, by id."
          },
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Job"
            },
            "description": "Single-stop visits to serve. At most 10,000 tasks per request, `jobs`\nand `shipments` combined (HTTP 400 `limit_exceeded` beyond that).",
            "maxItems": 10000
          },
          "objective": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Objective",
                "description": "Objective configuration."
              }
            ],
            "description": "Objective configuration."
          },
          "quotas": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Quota"
            },
            "description": "Stop caps shared by a set of vehicles. At most 65,535.",
            "maxItems": 65535
          },
          "relations": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Relation"
            },
            "description": "Ordering, co-assignment and synchronization constraints."
          },
          "shipments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            },
            "description": "Bound pickup→delivery shipments to serve. Counts toward the same\n10,000-task cap as `jobs`.",
            "maxItems": 10000
          },
          "travel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Travel",
                "description": "Where travel times and distances come from."
              }
            ],
            "description": "Where travel times and distances come from."
          },
          "vehicles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Vehicle"
            },
            "description": "Available vehicles: 1 to 2,000 (HTTP 400 otherwise).",
            "maxItems": 2000,
            "minItems": 1
          }
        },
        "additionalProperties": false,
        "example": {
          "depots": [
            {
              "id": "gent",
              "location": [
                3.7174,
                51.0543
              ]
            }
          ],
          "jobs": [
            {
              "id": "job-1",
              "location": [
                3.725,
                51.05
              ],
              "pickup_load": {
                "weight": 20
              },
              "service_duration_s": 300
            }
          ],
          "vehicles": [
            {
              "capacity": {
                "weight": 500
              },
              "id": "v1",
              "shifts": [
                {
                  "end": {
                    "depot": "gent"
                  },
                  "from": "2026-07-01T08:00:00+02:00",
                  "id": "mon",
                  "start": {
                    "depot": "gent"
                  },
                  "to": "2026-07-01T17:00:00+02:00"
                }
              ]
            }
          ]
        }
      },
      "Profile": {
        "type": "string",
        "description": "A vehicle's routing profile.",
        "enum": [
          "car",
          "truck",
          "bike"
        ],
        "example": "car"
      },
      "Quantities": {
        "type": "object",
        "description": "Named capacity/demand/load dimensions, e.g. `{\"weight\": 30, \"volume\": 2}`. Keys are user-chosen dimension names; values are integer quantities. Order-independent and self-documenting. In a request every value must be `>= 0` (a negative one is rejected with HTTP 400 `out_of_range`), and a request may use at most 4 distinct dimension names across jobs, shipments and vehicles (HTTP 400 `limit_exceeded` beyond that).",
        "additionalProperties": {
          "type": "integer",
          "format": "int32",
          "minimum": 0
        },
        "propertyNames": {
          "type": "string"
        },
        "example": {
          "volume": 2,
          "weight": 20
        }
      },
      "QuantityUnit": {
        "type": "string",
        "description": "The unit of a violation's `excess` or a relaxation's `amount`.\n\nKnown values: `s`, `m`, `load`, `stops`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "s",
        "x-extensible-enum": [
          "s",
          "m",
          "load",
          "stops"
        ]
      },
      "Quota": {
        "type": "object",
        "description": "A hard cap on how many stops of `tasks` the `vehicles` serve together\nin a window. A stop counts when its service starts in `[from, to)`\n(`arrival + wait_s` in the response when no windowed break is taken on\narrival there); without a window every stop counts.\nStops count as `max_stops` counts them: a job one, a shipment two. An\nover-cap job is left unassigned. Unlike `limits.periods[]`, which counts a\nshift by its start, a quota has no `every` recurrence and caps only stop\ncounts.",
        "required": [
          "id",
          "vehicles",
          "tasks",
          "max_stops"
        ],
        "properties": {
          "from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Window start (RFC 3339, UTC offset required), with `to`. The window\nmust overlap a shift of one of `vehicles` (counting its\n`max_overtime_s`), else the request is rejected with HTTP 400.",
            "example": "2026-10-05T00:00:00+02:00"
          },
          "id": {
            "type": "string",
            "description": "Quota id: 1 to 128 characters, unique among `quotas`; named in the\n`/evaluate` `quota` violation.",
            "maxLength": 128,
            "minLength": 1
          },
          "max_stops": {
            "type": "integer",
            "format": "uint32",
            "description": "The cap on counted stops; a job counts as one stop.\nStart, end, break and reload stops in `routes[].stops` do not count; a\nshipment counts as two stops.",
            "minimum": 0
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job or shipment ids whose stops count, each at most once. At least\none; an id that names no job or shipment is rejected with HTTP 400.",
            "minItems": 1
          },
          "to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Window end (RFC 3339, UTC offset required, exclusive), with `from`.",
            "example": "2026-10-06T00:00:00+02:00"
          },
          "vehicles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Vehicle ids that share the cap, each at most once. At least one; an id\nthat names no vehicle is rejected with HTTP 400.",
            "minItems": 1
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "pool-install",
          "max_stops": 2,
          "tasks": [
            "j1",
            "j2",
            "j3"
          ],
          "vehicles": [
            "c0",
            "c1"
          ]
        }
      },
      "Relation": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RelationSequence"
          },
          {
            "$ref": "#/components/schemas/RelationConsecutive"
          },
          {
            "$ref": "#/components/schemas/RelationTagOrder"
          },
          {
            "$ref": "#/components/schemas/RelationSameVehicle"
          },
          {
            "$ref": "#/components/schemas/RelationSameDay"
          },
          {
            "$ref": "#/components/schemas/RelationSameRoute"
          },
          {
            "$ref": "#/components/schemas/RelationSynchronized"
          },
          {
            "$ref": "#/components/schemas/RelationTimeLag"
          },
          {
            "$ref": "#/components/schemas/RelationCompatibleVehicles"
          },
          {
            "$ref": "#/components/schemas/RelationAllOrNone"
          }
        ],
        "description": "A hard constraint between tasks, selected by `type`: `sequence`,\n`consecutive`, `tag_order`, `same_vehicle`, `same_day`, `same_route`,\n`synchronized`, `time_lag`, `compatible_vehicles` or `all_or_none`.\nEach type carries only its own fields; any other `type` is rejected with\nHTTP 400.\n\nMembers are named by `stops` (job ids, or shipment-leg stop ids where\nthe type accepts them, see below). `same_vehicle`, `same_day` and\n`same_route` take **either** `stops` **or** a `tag`, not both. Every\nrelation is hard.\n\nA shipment takes part through its legs: `sequence`, `same_vehicle`,\n`same_day` and `same_route` accept a leg's stop id (`pickup.id` /\n`delivery.id`, by default `\"{shipment}:pickup\"` / `\":delivery\"`) and bind\nthat leg like a job. A leg coupled to other tasks by a `synchronized` or\n`time_lag` relation (directly, or through a `sequence` with a member that\nis) is rejected with HTTP 400, as is a `sequence` putting a delivery before\nits pickup. A shipment's own id in `stops`, or a shipment carrying the\n`tag` of a `same_vehicle` or `same_day` relation, is rejected with HTTP 400\n`not_supported`: relations never silently skip a member. `same_route`,\n`time_lag`, `compatible_vehicles` and `tag_order` reject a shipment with\nHTTP 400 as well. `all_or_none` alone takes a shipment's own id, naming both\nlegs, in a group that is exactly one `consecutive` chain; such a chain may\nalso be jobs only.",
        "example": {
          "stops": [
            "job-1",
            "job-2"
          ],
          "type": "sequence"
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "all_or_none": "#/components/schemas/RelationAllOrNone",
            "compatible_vehicles": "#/components/schemas/RelationCompatibleVehicles",
            "consecutive": "#/components/schemas/RelationConsecutive",
            "same_day": "#/components/schemas/RelationSameDay",
            "same_route": "#/components/schemas/RelationSameRoute",
            "same_vehicle": "#/components/schemas/RelationSameVehicle",
            "sequence": "#/components/schemas/RelationSequence",
            "synchronized": "#/components/schemas/RelationSynchronized",
            "tag_order": "#/components/schemas/RelationTagOrder",
            "time_lag": "#/components/schemas/RelationTimeLag"
          }
        }
      },
      "RelationAllOrNone": {
        "type": "object",
        "title": "All or none",
        "description": "All or none: either every member in `stops` is served, or none is.\nSets no timing; a coupled group takes its timing from the\n`synchronized` or `time_lag` relation that names its members. Hard.\nOverlapping `all_or_none` relations chain: one on A and B plus\none on B and C serve all three together or none of them. A group with\na task in a vehicle's locked prefix (`plan.routes[].locked_count`) is exempt. On\nsolve, a group a `pinned` plan stop would leave partly served comes back\nunassigned whole, its pins included. A member that could be served but is held back because\nanother cannot reports `all_or_none` in `unassigned[].reasons`; when the group did not fit\nwhole, each member of a group not coupled by `synchronized`/`time_lag` stays `time_limit` and also names what refused the member left over\n(`shift_end` for a chain longer than the shifts).\n\nA member may be a shipment id (both legs). Members are coupled by\n`synchronized`/`time_lag`, or the group's stops (a shipment as its two\nlegs) are exactly one `consecutive` chain with no member coupled by\n`synchronized` or `time_lag`, directly or through a `sequence` or\n`consecutive` relation. A task named by neither is rejected with HTTP 400, as is a\nshipment-leg id: name the shipment.",
        "required": [
          "stops",
          "type"
        ],
        "properties": {
          "stops": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment ids, at least two. A shipment-leg stop id is\nrejected with HTTP 400.",
            "example": [
              "job-1",
              "job-2"
            ],
            "minItems": 2
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `all_or_none`.",
            "enum": [
              "all_or_none"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationCompatibleVehicles": {
        "type": "object",
        "title": "Compatible vehicles",
        "description": "Which vehicles may serve a set of tasks together. Every two distinct\nvehicles serving `stops` must be compatible under\n`vehicles[].compatible_with`; with no lists it restricts nothing.\nTasks left unassigned impose nothing, so a group may be served\npartially. Hard.\n\nEvery task must also be named by a `synchronized` or `time_lag`\nrelation; a task named by neither is rejected with HTTP 400. At most\n16 tasks per relation.",
        "required": [
          "stops",
          "type"
        ],
        "properties": {
          "stops": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job ids, 2 to 16. A shipment's own id or a shipment-leg stop id\nis rejected with HTTP 400.",
            "example": [
              "job-1",
              "job-2"
            ],
            "maxItems": 16,
            "minItems": 2
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `compatible_vehicles`.",
            "enum": [
              "compatible_vehicles"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationConsecutive": {
        "type": "object",
        "title": "Consecutive",
        "description": "Ordering with no gap: like `sequence`, and in addition no other stop may\nsit between two neighbouring members that are served on the same\nroute. A member that is unassigned is skipped, so only listed\nneighbours that are both served are adjacent. Members on different\nroutes are unconstrained; add `same_route` to keep them together.\nPut a chain in an `all_or_none` to serve it whole or not at all.",
        "required": [
          "stops",
          "type"
        ],
        "properties": {
          "stops": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment-leg stop ids, in the order they must be served\nback to back. At least 2. A stop has one successor and one predecessor\nacross all `consecutive` relations, so `[a, b]` and `[b, c]` may\noverlap but `[a, b]` and `[a, c]` may not. A shipment's own id is rejected with HTTP\n400 `not_supported`.",
            "minItems": 2
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `consecutive`.",
            "enum": [
              "consecutive"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationInstant": {
        "type": "string",
        "description": "Which instant of a member a `synchronized` or `time_lag` relation is\nmeasured at, named after the response stop field that reports it. There is\nno `arrival`: a relation bounds when service happens, not when the vehicle\ngets there.",
        "enum": [
          "service_start",
          "departure"
        ]
      },
      "RelationSameDay": {
        "type": "object",
        "title": "Same day",
        "description": "Same calendar day: every member that is served is served on the same\nday. The day is the calendar date of the serving shift's `from`, read\nin that value's own UTC offset, not the time of the stop. Like\n`same_vehicle`, it constrains only the members that end up assigned.",
        "required": [
          "type"
        ],
        "properties": {
          "stops": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment-leg stop ids in the relation (mutually\nexclusive with `tag`). A shipment's own id is rejected with\nHTTP 400 `not_supported`."
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tag selecting the relation members (mutually exclusive with `stops`)."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `same_day`.",
            "enum": [
              "same_day"
            ]
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "stops": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "stops"
                  ]
                }
              ]
            },
            "required": [
              "stops"
            ]
          },
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "tag": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "tag"
                  ]
                }
              ]
            },
            "required": [
              "tag"
            ]
          }
        ]
      },
      "RelationSameRoute": {
        "type": "object",
        "title": "Same route",
        "description": "Same route: every member that ends up assigned is served by one\nvehicle shift (one entry of `shifts`), stricter than\n`same_vehicle` for vehicles with several `shifts`. Reloads within\nthe shift do not split a route. Hard-only, with `same_vehicle`'s\npartial-service semantics.",
        "required": [
          "type"
        ],
        "properties": {
          "stops": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment-leg stop ids in the relation (mutually\nexclusive with `tag`). A shipment's own id is rejected with HTTP\n400."
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tag selecting the relation members (mutually exclusive with `stops`)."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `same_route`.",
            "enum": [
              "same_route"
            ]
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "stops": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "stops"
                  ]
                }
              ]
            },
            "required": [
              "stops"
            ]
          },
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "tag": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "tag"
                  ]
                }
              ]
            },
            "required": [
              "tag"
            ]
          }
        ]
      },
      "RelationSameVehicle": {
        "type": "object",
        "title": "Same vehicle",
        "description": "Same vehicle: every member that is served is served by the same\nvehicle, on any of its shifts.",
        "required": [
          "type"
        ],
        "properties": {
          "stops": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment-leg stop ids in the relation (mutually\nexclusive with `tag`). A shipment's own id is rejected with\nHTTP 400 `not_supported`."
          },
          "tag": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tag selecting the relation members (mutually exclusive with `stops`)."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `same_vehicle`.",
            "enum": [
              "same_vehicle"
            ]
          }
        },
        "additionalProperties": false,
        "oneOf": [
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "stops": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "stops"
                  ]
                }
              ]
            },
            "required": [
              "stops"
            ]
          },
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "tag": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "tag"
                  ]
                }
              ]
            },
            "required": [
              "tag"
            ]
          }
        ]
      },
      "RelationSequence": {
        "type": "object",
        "title": "Sequence",
        "description": "Ordering (gaps allowed). **Pitfall.** It constrains members that end\nup on the **same route** only and does not force them onto one route:\nmembers on different vehicles are unordered relative to each other.\nAdd `same_route` to keep them together.",
        "required": [
          "stops",
          "type"
        ],
        "properties": {
          "stops": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Job ids or shipment-leg stop ids (`pickup.id` / `delivery.id`, by\ndefault `\"{shipment}:pickup\"` / `\"{shipment}:delivery\"`), in the\norder they must be served. **Pitfall.** A shipment's own id is\nrejected with HTTP 400 `not_supported`; only `all_or_none` takes\none. Name the shipment's legs instead."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `sequence`.",
            "enum": [
              "sequence"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationSynchronized": {
        "type": "object",
        "title": "Synchronized",
        "description": "Synchronized starts (or ends) across vehicles: every member's\nservice start — or with `on: departure`, its service end — lies within\n`max_spread_s` seconds of every other member's. Hard, checked across\nroutes; the returned schedule holds a member back where needed so\nthe bound is met (see `hold_s` on the stop). A hold waits inside the\nregular shift only: a member is never held past its shift's `to`\ninto overtime (`max_overtime_s`); a group that could only meet the\nbound that way is left unassigned instead.",
        "required": [
          "max_spread_s",
          "stops",
          "type"
        ],
        "properties": {
          "max_spread_s": {
            "type": "integer",
            "format": "int64",
            "description": "Maximum spread between the synchronized instants in seconds\n(`0` = exact simultaneity). Required. A negative value, or one above\n2,147,483,647, is rejected with HTTP 400 `out_of_range`.",
            "maximum": 2147483647,
            "minimum": 0
          },
          "on": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/RelationInstant",
                "description": "Which instant is synchronized: `service_start` (default) or\n`departure` (the service end), the stop fields of the same names."
              }
            ],
            "description": "Which instant is synchronized: `service_start` (default) or\n`departure` (the service end), the stop fields of the same names.",
            "default": "service_start"
          },
          "stops": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Participating job ids, at most 8 (HTTP 400 `limit_exceeded`\nbeyond that). A shipment-leg stop id is rejected with HTTP 400;\na shipment's own id with HTTP 400 `not_supported`.",
            "maxItems": 8
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `synchronized`.",
            "enum": [
              "synchronized"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationTagOrder": {
        "type": "object",
        "title": "Tag order",
        "description": "Ordering between tags: on every route, every task carrying `tags[0]`\nprecedes every task carrying `tags[1]`, and so on. Tasks carry\nmembership via their own `tags`. At most one `tag_order` per request.\n\nJobs only: if a tag named here selects a **shipment**, the request is\nrejected with HTTP 400 (a shipment's two legs already carry their own\nhard precedence, which tag ordering does not combine with). Drop the\ntag from the shipment.",
        "required": [
          "tags",
          "type"
        ],
        "properties": {
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tag labels in precedence order. Requires at least 2 entries.",
            "minItems": 2
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `tag_order`.",
            "enum": [
              "tag_order"
            ]
          }
        },
        "additionalProperties": false
      },
      "RelationTimeLag": {
        "type": "object",
        "title": "Time lag",
        "description": "A directional time bound between two jobs on any vehicles:\n`t(to) − t(from)` must lie in `[min_s, max_s]` seconds, each end\nmeasured at the job's service start or end (`on`). \"B starts at\nleast an hour after A ends\" is `from: {stop: A, on: departure}, to: {stop: B},\nmin_s: 3600`; \"A and B finish together\" is both ends `on: departure` with\n`min_s: 0, max_s: 0`. `min_s` defaults to `0`; an absent `max_s` is\nunbounded; both may be negative. Hard, checked across routes like\n`synchronized` (an unassigned end imposes nothing). A job may take\npart in any number of `time_lag` relations; a chain is written as\none relation per consecutive pair. As with `synchronized`, a hold\nnever waits past the shift's regular end (`to`).",
        "required": [
          "from",
          "to",
          "type"
        ],
        "properties": {
          "from": {
            "$ref": "#/components/schemas/TimeLagMember",
            "description": "The reference end."
          },
          "max_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Upper bound on `t(to) − t(from)` in seconds. Absent = unbounded.\nFrom −2,147,483,648 to 2,147,483,647 and `>= min_s` (HTTP 400\notherwise).",
            "maximum": 2147483647,
            "minimum": -2147483648
          },
          "min_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Lower bound on `t(to) − t(from)` in seconds. Default `0`. From\n−2,147,483,648 to 2,147,483,647.",
            "default": 0,
            "maximum": 2147483647,
            "minimum": -2147483648
          },
          "to": {
            "$ref": "#/components/schemas/TimeLagMember",
            "description": "The bounded end."
          },
          "type": {
            "type": "string",
            "description": "Discriminator: always `time_lag`.",
            "enum": [
              "time_lag"
            ]
          }
        },
        "additionalProperties": false
      },
      "Relaxation": {
        "type": "object",
        "description": "A best-effort, actionable suggestion for relaxing the problem so a task can be\nassigned — derived from the smallest constraint relaxation the solver found.\nIt comes only from a shift that capacity and time windows alone refuse: a\nshift also refused by a skill, a tag, eligibility, its shift end or any\nother rule suggests nothing.",
        "required": [
          "pointer",
          "op",
          "amount",
          "unit",
          "message"
        ],
        "properties": {
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Magnitude of the change, expressed in `unit`.",
            "example": 900
          },
          "message": {
            "type": "string",
            "description": "Human-readable suggestion.",
            "example": "Extend a time window by 900s (~15 min)."
          },
          "op": {
            "$ref": "#/components/schemas/RelaxationOp",
            "description": "The kind of change suggested."
          },
          "pointer": {
            "type": "string",
            "description": "[RFC 6901] JSON Pointer to the request field to change, like\n`warnings[].pointer`. For a job: `/problem/jobs/{i}/pickup_load`\n(`/problem/jobs/{i}/delivery_load` for a job with only a\n`delivery_load`) or `/problem/jobs/{i}/time_windows`. For a shipment:\n`/problem/shipments/{i}/load` or `/problem/shipments/{i}/pickup/time_windows`\n(either leg's window may be the one to extend). It may name a field the\nrequest omits (a JSON Patch `add` target); its task prefix always resolves.\n\n[RFC 6901]: https://www.rfc-editor.org/rfc/rfc6901",
            "example": "/problem/jobs/1/time_windows"
          },
          "unit": {
            "$ref": "#/components/schemas/QuantityUnit",
            "description": "Unit of `amount`: `s` for `extend_time_window`, `load` for `reduce_load`."
          }
        },
        "example": {
          "amount": 900,
          "message": "Extend a time window by 900s (~15 min).",
          "op": "extend_time_window",
          "pointer": "/problem/jobs/1/time_windows",
          "unit": "s"
        }
      },
      "RelaxationOp": {
        "type": "string",
        "description": "The kind of change a relaxation suggests.\n\nKnown values: `reduce_load`, `extend_time_window`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "extend_time_window",
        "x-extensible-enum": [
          "reduce_load",
          "extend_time_window"
        ]
      },
      "RequestIssue": {
        "type": "object",
        "description": "One problem in a request.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "actual": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint64",
            "description": "`limit_exceeded` only: the count this request has.",
            "minimum": 0
          },
          "code": {
            "$ref": "#/components/schemas/ErrorItemCode",
            "description": "What is wrong."
          },
          "limit": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint64",
            "description": "`limit_exceeded` only: the published cap.",
            "minimum": 0
          },
          "message": {
            "type": "string",
            "description": "Human-readable description."
          },
          "pointer": {
            "type": [
              "string",
              "null"
            ],
            "description": "RFC 6901 JSON Pointer into the request body, when the problem has a\nlocation. It is relative to the root of the body, so a field of the\nproblem reads `/problem/...` (e.g.\n`\"/problem/vehicles/0/shifts/0/from\"`)."
          }
        }
      },
      "RequestWarning": {
        "type": "object",
        "description": "One advisory on a successful response (`warnings[]` on solve, suggest,\nevaluate, validate and an async run's plan): something the request carried that was adjusted or that\nchanged nothing. Never a failure: the request was served as documented.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/WarningCode",
            "description": "What kind of advisory this is. Branch on it."
          },
          "message": {
            "type": "string",
            "description": "Human-readable description. Do not parse it."
          },
          "pointer": {
            "type": [
              "string",
              "null"
            ],
            "description": "RFC 6901 JSON Pointer to the field concerned, from the root of the\nrequest body (`/options/time_limit_s`, `/plan/routes/0/stops`).\nAbsent when the advisory has no single field."
          }
        },
        "example": {
          "code": "time_limit_raised",
          "message": "options.time_limit_s: 0.01 is below the 0.1 s floor and is raised to 0.1 s",
          "pointer": "/options/time_limit_s"
        }
      },
      "Route": {
        "type": "object",
        "description": "A single vehicle's route.",
        "required": [
          "vehicle",
          "shift",
          "distance_m",
          "time",
          "stops"
        ],
        "properties": {
          "distance_m": {
            "type": "integer",
            "format": "int64",
            "description": "Total route distance, in metres.",
            "example": 8450
          },
          "load_peak": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Peak load reached on the route, by named dimension."
              }
            ],
            "description": "Peak load reached on the route, by named dimension."
          },
          "polyline": {
            "type": [
              "string",
              "null"
            ],
            "description": "Road geometry for this route as an [encoded polyline] at precision 5\n(~1.1 m), ready to hand to a map library. Present only when\n`options.polyline` was set, and absent for a route whose geometry the\nrouting engine could not produce.\n\nTraced with this vehicle's `profile` at the solve's departure time, so\nit is the same road path the plan was costed on — not a generic car\nroute. It is a decoration, though: `distance_m` and `time` come\nfrom the solver's matrix and are authoritative if the two ever disagree.\n\n[encoded polyline]: https://developers.google.com/maps/documentation/utilities/polylinealgorithm",
            "example": "_p~iF~ps|U_ulLnnqC_mqNvxq`@"
          },
          "shift": {
            "type": "string",
            "description": "The shift id (`vehicles[].shifts[].id`) this route runs on.",
            "example": "mon"
          },
          "stops": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RouteStop"
            },
            "description": "Stops in time order (by `departure`), including depot bookends. A\nwindowed break taken while the vehicle is at a stop is listed just\nbefore that stop and lies within that stop's `arrival` to `departure`\n(the end stop included); drive, duty and unavailability breaks end\nbefore the next stop's `arrival`."
          },
          "time": {
            "$ref": "#/components/schemas/TimeTotals",
            "description": "Where this route's time goes. `time.span_s` is what the route's\n`costs.per_route_hour` is charged on: the shift's rate, else its\nvehicle's, else `objective.costs.per_route_hour`."
          },
          "vehicle": {
            "type": "string",
            "description": "The vehicle id (`vehicle.id` from the request) serving this route."
          },
          "violations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Violation"
            },
            "description": "Route-level constraint violations (e.g. `max_distance`, `max_route_duration`,\nor `unreachable` for a leg whose destination is not a job stop — the\nreturn to the end depot, or a leg into a reload).\nOnly populated by `POST /v3/routing/evaluate`; absent on solve responses."
          }
        },
        "example": {
          "distance_m": 8450,
          "load_peak": {
            "weight": 55
          },
          "shift": "mon",
          "stops": [
            {
              "arrival": "2026-07-01T08:00:00+02:00",
              "departure": "2026-07-01T08:00:00+02:00",
              "depot": "gent",
              "load_after": {
                "weight": 0
              },
              "location": [
                3.7174,
                51.0543
              ],
              "service_s": 0,
              "type": "start"
            },
            {
              "arrival": "2026-07-01T08:10:00+02:00",
              "departure": "2026-07-01T09:05:00+02:00",
              "distance_m": 2600,
              "id": "job-1",
              "lateness_s": 0,
              "load_after": {
                "weight": 20
              },
              "location": [
                3.725,
                51.05
              ],
              "service_s": 300,
              "service_start": "2026-07-01T09:00:00+02:00",
              "travel_s": 600,
              "type": "job",
              "wait_s": 3000
            },
            {
              "arrival": "2026-07-01T09:13:00+02:00",
              "departure": "2026-07-01T09:23:00+02:00",
              "distance_m": 2350,
              "id": "job-2",
              "lateness_s": 0,
              "load_after": {
                "weight": 55
              },
              "location": [
                3.71,
                51.06
              ],
              "service_s": 600,
              "service_start": "2026-07-01T09:13:00+02:00",
              "travel_s": 480,
              "type": "job",
              "wait_s": 0
            },
            {
              "arrival": "2026-07-01T09:38:00+02:00",
              "departure": "2026-07-01T09:38:00+02:00",
              "depot": "gent",
              "distance_m": 3500,
              "load_after": {
                "weight": 55
              },
              "location": [
                3.7174,
                51.0543
              ],
              "service_s": 0,
              "travel_s": 900,
              "type": "end",
              "wait_s": 0
            }
          ],
          "time": {
            "break_s": 0,
            "depot_s": 0,
            "overtime_s": 0,
            "service_s": 900,
            "span_s": 5880,
            "travel_s": 1980,
            "wait_s": 3000
          },
          "vehicle": "v1"
        }
      },
      "RouteStop": {
        "type": "object",
        "description": "A single stop within a route.\n\nOne flat object for every stop `type`. `type`, `arrival` and `departure`\nare present on every stop; every other field is present only on the stop\ntypes its description names, and absent (not `null`) elsewhere:\n\n| `type` | fields beyond `type`, `arrival`, `departure` |\n| --- | --- |\n| `job`, `pickup`, `delivery` | `id`, `location`, `service_start`, `wait_s`, `service_s`, `travel_s`, `distance_m`, `lateness_s`; `hold_s`, `target_lateness_s`, `violations` when they apply |\n| `start` | `depot`, `location`, `service_s` (absent on an open start) |\n| `end` | `depot`, `location`, `wait_s`, `service_s` (absent on an open end), `travel_s`, `distance_m` |\n| `reload` | `depot`, `location`, `service_start`, `wait_s`, `service_s`, `travel_s`, `distance_m` |\n| `break` | `id` (when the request break names one), `service_s` |\n\n`load_after` is on every stop when the problem declares a capacity\ndimension, and `snapped_location` wherever there is a `location` and the\nrouting graph snapped it.\n\nEvery stop time is RFC 3339, rendered in the UTC offset of the route's\nshift `from` (`Z` when that `from` is UTC or has no offset): a `+02:00`\nshift reports `2026-07-01T08:10:00+02:00`, the same instant as\n`2026-07-01T06:10:00Z`.",
        "required": [
          "type",
          "arrival",
          "departure"
        ],
        "properties": {
          "arrival": {
            "type": "string",
            "format": "date-time",
            "description": "Physical arrival, before any waiting. On `start` when the route\nbegins; on `break` when the break starts.",
            "example": "2026-07-01T08:10:00+02:00"
          },
          "break_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Seconds of driver break taken inside this stop's service, pausing it:\na `fixed`, `windowed` or `triggered` break that fell mid-service on a\njob with `break_interruptible: true`. Such a break gets no `break`\nstop of its own; its time is counted here and in the route's\n`time.break_s`. The stop reconciles as\n`departure - service_start == service_s + setup + break_s`, where\nsetup is the unscaled `setup_duration_s` when paid, else 0. Present on\n`job` stops only, when non-zero.",
            "example": 3600
          },
          "departure": {
            "type": "string",
            "format": "date-time",
            "description": "Departure. On `end` when the route finishes, after any depot\nhandling time; on `break` when the break ends (`arrival + service_s`).",
            "example": "2026-07-01T09:05:00+02:00"
          },
          "depot": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `depots[].id` of this stop: on every `reload` stop, and on a\n`start`/`end` stop whose shift end names a depot. Absent on a\n`location` or open end and on task and break stops.",
            "example": "gent"
          },
          "distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Travel distance from the previous stop, in metres. On task, `reload`\nand `end` stops.",
            "example": 2600
          },
          "hold_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "The part of `wait_s` spent holding for a `synchronized` or\n`time_lag` partner on another vehicle, beyond any wait the time\nwindow already imposed. On task stops, only when non-zero.",
            "example": 0
          },
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "On a `job` stop the job id; on `pickup`/`delivery` the leg's stop id\n(its own `id`, else `{shipment}:pickup` / `{shipment}:delivery`); on a\n`break` stop the `id` of the request break (`shifts[].breaks[].id`)\nit realises, absent when that break named none. Absent on `start`,\n`end` and `reload`.",
            "example": "job-1"
          },
          "lateness_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Seconds the start of service is past the time window's `to` (`0` when\non time), on task stops, measured from the arrival plus any `windowed`\nbreak taken on arrival at this stop (idle until that break's window\nopens included). Measures the time window only; a soft target is\nreported in `target_lateness_s`.",
            "example": 0
          },
          "load_after": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Load on board after this stop, by named dimension: on `start` when\nthe vehicle leaves, on `reload` the next trip's departure stock, on\n`break` the load after the previous stop. Absent when the problem\ndeclares no capacity dimension."
              }
            ],
            "description": "Load on board after this stop, by named dimension: on `start` when\nthe vehicle leaves, on `reload` the next trip's departure stock, on\n`break` the load after the previous stop. Absent when the problem\ndeclares no capacity dimension."
          },
          "location": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number",
              "format": "double"
            },
            "description": "Stop location `[longitude, latitude]` (GeoJSON order). Absent on\nevery `break` stop, and on\n`start`/`end` stops for a genuinely open end (no configured\ncoordinate for that end of the shift). A virtual (location-less) job\nhas no coordinate of its own and reports its nearest located\nneighbor's instead, so it is absent only when the whole route is\nvirtual with open depot ends.",
            "example": [
              3.725,
              51.05
            ],
            "maxItems": 2,
            "minItems": 2
          },
          "service_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Time spent at this stop, in seconds.\n\nOn task stops, the **effective** on-site service time, not the\nnominal `service_duration_s` from the request: it already has the\nserving vehicle's `service_factor` applied. `departure -\nservice_start - service_s - break_s` is the stop's setup time: the\nrequest's `setup_duration_s` (unscaled) for the first stop of a run at\nthe same location (setup is charged when the previous stop is\nelsewhere), and 0 for a co-located successor.\n\nOn `reload`, the depot's handling time (`departure - service_start\n== service_s`). On `start`/`end`, the depot handling time applied\nthere (0 on a free-travel end), so `departure - arrival == service_s`\non a start and `departure - arrival - wait_s - Σ windowed break\nservice_s == service_s` on an end; absent on an open start or end. On `break`, the\nbreak length (`departure - arrival`). `service_factor` never scales\ndepot, reload or break time.",
            "example": 300
          },
          "service_start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When service starts: `arrival + wait_s` plus the duration of any\nbreak taken on arrival here (a `windowed` one; on a\n`break_interruptible` job also a `fixed` or duty-`triggered` one that\nfalls in the wait). On task and `reload` stops only.",
            "example": "2026-07-01T09:00:00+02:00"
          },
          "snapped_location": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "number",
              "format": "double"
            },
            "description": "The same point snapped to the routable graph, when available.",
            "maxItems": 2,
            "minItems": 2
          },
          "target_lateness_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Seconds past this task's `target.at`, measured at the stop's arrival\n(plus any `windowed` break taken on arrival there, idle before it\nincluded) or departure per `target.on`; `0` when met. Present only on a task\nstop carrying a target. A shipment's own `target` is measured on its\ndelivery leg, so it appears on the `:delivery` stop; a `pickup.target`\nor `delivery.target` appears on that leg's stop.",
            "example": 0
          },
          "travel_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Travel time from the previous stop, in seconds. On task, `reload`\nand `end` stops.",
            "example": 600
          },
          "type": {
            "$ref": "#/components/schemas/StopType",
            "description": "What kind of stop this is."
          },
          "violations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Violation"
            },
            "description": "Constraint violations detected at this task stop, populated by\n`POST /v3/routing/evaluate` (imported solutions may be infeasible). On\na solve response it is absent, unless a `pinned` plan stop forces a\nrelation breach (see `Summary.score`)."
          },
          "wait_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Seconds spent waiting here, counted in `time.wait_s`. On task stops:\nbefore service, for the time window to open and for any cross-route\nhold (`hold_s`, included in this figure). On `reload`: before the\nreload. On both, also the idle before a windowed break taken on\narrival here whose window had not opened yet, so `service_start ==\narrival + wait_s + Σ` those breaks' `service_s`. On `end`: idle time\nat the end, `departure - arrival - service_s` less the `service_s` of\nbreak stops taken there, clamped to be never negative. Idle before a\nbreak is not charged by `per_wait_hour`. Absent on `start` (a start\nnever waits) and `break`.",
            "example": 3000
          }
        },
        "example": {
          "arrival": "2026-07-01T08:10:00+02:00",
          "departure": "2026-07-01T09:05:00+02:00",
          "distance_m": 2600,
          "id": "job-1",
          "lateness_s": 0,
          "load_after": {
            "weight": 20
          },
          "location": [
            3.725,
            51.05
          ],
          "service_s": 300,
          "service_start": "2026-07-01T09:00:00+02:00",
          "travel_s": 600,
          "type": "job",
          "wait_s": 3000
        }
      },
      "Score": {
        "type": "object",
        "description": "How good a plan is. Plans compare in order: fewer `violation_count`\nfirst, then less `unassigned_priority`, then less `cost`.",
        "required": [
          "violation_count",
          "unassigned_priority",
          "cost",
          "components"
        ],
        "properties": {
          "components": {
            "$ref": "#/components/schemas/ScoreComponents",
            "description": "The money of each objective term."
          },
          "cost": {
            "type": "number",
            "format": "double",
            "description": "Total cost, in the objective's currency: the sum of `components`.",
            "example": 58.8436
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Informational currency label, echoed from `objective.currency`.",
            "example": "EUR"
          },
          "unassigned_priority": {
            "type": "integer",
            "format": "int64",
            "description": "Summed `priority` of the required tasks left unassigned (a task that\npriced a `drop_cost` counts in `components.drop_costs` instead).",
            "example": 0
          },
          "violation_count": {
            "type": "integer",
            "format": "uint32",
            "description": "How many hard-constraint violations the plan has (the `violations`\narrays on routes and stops list them). On a solve result it is `0`\nunless a `pinned` plan stop forces a relation breach (see\n`Summary.score`); on evaluate it counts the breaches in the given plan.",
            "example": 0,
            "minimum": 0
          }
        },
        "example": {
          "components": {
            "assignment": 0.0,
            "delay": 0.0,
            "distance": 1.69,
            "driving": 0.0,
            "drop_costs": 0.0,
            "grouping": 0.0,
            "lateness": 0.0,
            "overtime": 0.0,
            "preferences": 0.0,
            "reloads": 0.0,
            "routes": 0.0,
            "stops": 0.0,
            "tag_preference": 0.0,
            "target": 0.0,
            "time": 57.1536,
            "vehicles": 0.0,
            "waiting": 0.0,
            "window_choice": 0.0,
            "workload_share": 0.0
          },
          "cost": 58.8436,
          "currency": "EUR",
          "unassigned_priority": 0,
          "violation_count": 0
        }
      },
      "ScoreComponents": {
        "type": "object",
        "description": "The money of each objective term, in the objective's currency. The\ncomponents always sum to `score.cost` exactly: every term the solver\ncharges lands in exactly one of them.",
        "required": [
          "routes",
          "stops",
          "vehicles",
          "time",
          "distance",
          "waiting",
          "driving",
          "overtime",
          "lateness",
          "window_choice",
          "target",
          "tag_preference",
          "reloads",
          "grouping",
          "workload_share",
          "drop_costs",
          "preferences",
          "assignment",
          "delay"
        ],
        "properties": {
          "assignment": {
            "type": "number",
            "format": "double",
            "description": "Cost of the serving vehicle's `assignment_costs[].cost`, in currency\nunits."
          },
          "delay": {
            "type": "number",
            "format": "double",
            "description": "Cost of delay, in currency units (`objective.per_delay_workday`): each\nserved task pays the rate once per workday its shift lies after the\nearliest workday in the request."
          },
          "distance": {
            "type": "number",
            "format": "double",
            "description": "Distance cost, in currency units: each route's distance priced at\nits `costs.per_travel_km` (shift, vehicle or fleet)."
          },
          "driving": {
            "type": "number",
            "format": "double",
            "description": "Driving cost, in currency units: each route's `time.travel_s` priced at\nits `costs.per_drive_hour` (shift, vehicle or fleet). On top of `time`,\nwhich prices the same seconds within the span; the distance of those\nlegs is in `distance`."
          },
          "drop_costs": {
            "type": "number",
            "format": "double",
            "description": "The summed `drop_cost` of the tasks left unassigned, in currency units."
          },
          "grouping": {
            "type": "number",
            "format": "double",
            "description": "Cost of splitting close tasks across routes, in currency units\n(`objective.grouping`)."
          },
          "lateness": {
            "type": "number",
            "format": "double",
            "description": "Cost of priced lateness past a time window, in currency units\n(`objective.per_late_hour` or `time_windows[].per_late_hour`)."
          },
          "overtime": {
            "type": "number",
            "format": "double",
            "description": "Cost of work past a soft shift end, in currency units: priced at the\nroute's `costs.per_overtime_hour`."
          },
          "preferences": {
            "type": "number",
            "format": "double",
            "description": "Cost of `preferences[].violation_cost`, in currency units: paid for\neach listed vehicle that did not serve the task. Tag preferences are\n`tag_preference`."
          },
          "reloads": {
            "type": "number",
            "format": "double",
            "description": "Cost of reload visits, in currency units (`depots[].per_reload`)."
          },
          "routes": {
            "type": "number",
            "format": "double",
            "description": "Shift cost, in currency units: `costs.per_route` once per used shift,\nat the shift's, vehicle's or fleet's rate."
          },
          "stops": {
            "type": "number",
            "format": "double",
            "description": "Stop cost, in currency units: `costs.per_stop` for each stop of a used\nshift, or for `costs.min_billed_stops` when the shift has fewer, at\nthe shift's, vehicle's or fleet's rate."
          },
          "tag_preference": {
            "type": "number",
            "format": "double",
            "description": "Cost of serving tasks outside a vehicle's `preferred_tags`, in\ncurrency units."
          },
          "target": {
            "type": "number",
            "format": "double",
            "description": "Cost of missing tasks' `target` times, in currency units\n(`target.per_late_hour`)."
          },
          "time": {
            "type": "number",
            "format": "double",
            "description": "Time cost, in currency units: each route's span priced at its\n`costs.per_route_hour` (shift, vehicle or fleet)."
          },
          "vehicles": {
            "type": "number",
            "format": "double",
            "description": "Vehicle cost, in currency units: `costs.per_used_vehicle` once per\nvehicle that serves a task, however many of its shifts it works, at the\nvehicle's or fleet's rate."
          },
          "waiting": {
            "type": "number",
            "format": "double",
            "description": "Cost of waiting for time windows to open, in currency units: each\nroute's wait priced at its `costs.per_wait_hour`. Idle before a\nwindowed break opens is in `time.wait_s` but not priced here."
          },
          "window_choice": {
            "type": "number",
            "format": "double",
            "description": "The price of the time window each task was served in, in currency\nunits (`time_windows[].choice_cost`)."
          },
          "workload_share": {
            "type": "number",
            "format": "double",
            "description": "Workload outside the equal-share band, in currency units\n(`objective.workload_share`)."
          }
        },
        "example": {
          "assignment": 0.0,
          "delay": 0.0,
          "distance": 1.69,
          "driving": 0.0,
          "drop_costs": 0.0,
          "grouping": 0.0,
          "lateness": 0.0,
          "overtime": 0.0,
          "preferences": 0.0,
          "reloads": 0.0,
          "routes": 0.0,
          "stops": 0.0,
          "tag_preference": 0.0,
          "target": 0.0,
          "time": 57.1536,
          "vehicles": 0.0,
          "waiting": 0.0,
          "window_choice": 0.0,
          "workload_share": 0.0
        }
      },
      "SearchInfo": {
        "type": "object",
        "description": "How the search behind a plan ended.",
        "required": [
          "termination",
          "iterations"
        ],
        "properties": {
          "iterations": {
            "type": "integer",
            "format": "uint64",
            "description": "Search iterations performed. `0` when nothing was searched.",
            "example": 48210,
            "minimum": 0
          },
          "termination": {
            "$ref": "#/components/schemas/SearchTermination",
            "description": "How the search ended."
          }
        }
      },
      "SearchProgressPoint": {
        "type": "object",
        "description": "One point of `search_progress`: the best plan's score `elapsed_ms` into\nthe search. `unassigned_priority` and `cost` mean what they mean in\n`summary.score`; the best plan has the lowest `unassigned_priority`, then the\nlowest `cost`, so `cost` can rise when more tasks get served.",
        "required": [
          "elapsed_ms",
          "unassigned_priority",
          "cost"
        ],
        "properties": {
          "cost": {
            "type": "number",
            "format": "double",
            "description": "Total cost, in the objective's currency."
          },
          "elapsed_ms": {
            "type": "integer",
            "format": "uint64",
            "description": "Milliseconds since the solve started, building the first plan\nincluded (the clock of `summary.timings.search_ms`).",
            "minimum": 0
          },
          "unassigned_priority": {
            "type": "integer",
            "format": "int64",
            "description": "Summed `priority` of the required tasks left unassigned."
          }
        },
        "example": {
          "cost": 58.8436,
          "elapsed_ms": 180,
          "unassigned_priority": 0
        }
      },
      "SearchTermination": {
        "type": "string",
        "description": "How the search ended. New values may be added; clients must accept\nunknown values.\n\nKnown values: `time_limit`, `no_improvement`, `not_searched`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "x-extensible-enum": [
          "time_limit",
          "no_improvement",
          "not_searched"
        ]
      },
      "ServiceFactor": {
        "type": "object",
        "description": "Per-vehicle work-rate override for one task's `service_duration_s`.",
        "required": [
          "vehicle",
          "factor"
        ],
        "properties": {
          "factor": {
            "type": "number",
            "format": "double",
            "description": "Work-rate factor of `vehicle` on this task. Service time is DIVIDED by\nit: above `1` the vehicle works faster here, below `1` slower; `1.0` is a\nno-op. It multiplies the vehicle's own rate (the shift's\n`service_factor` if set, else the vehicle's): effective service time =\n`service_duration_s / (shift_or_vehicle_factor * factor)`. Same\ndirection and `[0.001, 5]` range as `vehicles[].service_factor`.\nMigrating from V2: `proficiency.durationModifier` multiplied duration\ninstead, so send `1 / durationModifier` here.",
            "example": 1.25,
            "maximum": 5,
            "minimum": 0.001
          },
          "vehicle": {
            "type": "string",
            "description": "Vehicle id; applies to every shift of that vehicle.",
            "example": "v1"
          }
        },
        "additionalProperties": false,
        "example": {
          "factor": 1.25,
          "vehicle": "v1"
        }
      },
      "Shift": {
        "type": "object",
        "description": "One working shift for a vehicle.",
        "required": [
          "id",
          "from",
          "to"
        ],
        "properties": {
          "breaks": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Break"
            },
            "description": "Scheduled driver breaks within this shift — see the `Break` schema for\nthe supported forms. Injected breaks appear as `break` stops in the\nresponse routes."
          },
          "capacity": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Capacity for this shift only. Each dimension named here replaces the\nvehicle's value for that dimension; dimensions not named keep the\nvehicle's `capacity`."
              }
            ],
            "description": "Capacity for this shift only. Each dimension named here replaces the\nvehicle's value for that dimension; dimensions not named keep the\nvehicle's `capacity`."
          },
          "costs": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ShiftCosts",
                "description": "Costs for this shift only. Each field set here replaces the same\nfield of the vehicle's `costs` (or, when the vehicle does not set it,\nof `objective.costs`) for this shift; fields not set keep that value.\n`per_used_vehicle` is not accepted here: it prices the vehicle, not a\nshift."
              }
            ],
            "description": "Costs for this shift only. Each field set here replaces the same\nfield of the vehicle's `costs` (or, when the vehicle does not set it,\nof `objective.costs`) for this shift; fields not set keep that value.\n`per_used_vehicle` is not accepted here: it prices the vehicle, not a\nshift."
          },
          "end": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ShiftPlace",
                "description": "Where the shift ends. **Default.** Absent: an open end, the route\nfinishes at its last task."
              }
            ],
            "description": "Where the shift ends. **Default.** Absent: an open end, the route\nfinishes at its last task."
          },
          "free_end_travel": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Symmetric to `free_start_travel` for travel from the last task to\n`end`; `true` without `end` is a 400.",
            "example": false
          },
          "free_start_travel": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "When `true`, travel from `start` to the first task is free: it takes\nno time and costs nothing, and is left out of the route's distance\nand duration. The depot is still reported (a real stop, snapped\ncoordinate, departure time). Distinct from omitting `start` (an open\nroute, which drops the depot entirely). `true` without `start` is\nrejected with HTTP 400 `conflicting_fields`. Default `false`.",
            "example": false
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Shift start (RFC 3339 instant, UTC offset required).",
            "example": "2026-07-01T08:00:00+02:00"
          },
          "id": {
            "type": "string",
            "description": "Shift id: 1 to 128 characters, unique within this vehicle.",
            "example": "mon",
            "maxLength": 128,
            "minLength": 1
          },
          "initial_load": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Load already on the vehicle at shift start (pre-loaded), per\ndimension. Occupies capacity on the first trip only — flushed at the\nfirst reload — so it reduces first-trip room per dimension, enforced\nby the per-trip capacity constraint. A value above the capacity in that\ndimension is rejected with HTTP 400 (`out_of_range`). The capacity is\nresolved per dimension: the shift's capacity when it defines the\ndimension, otherwise the vehicle's. If the vehicle has a capacity map\nthat omits the dimension, the capacity is `0`; if the vehicle has no\ncapacity map and the shift does not define the dimension, it is\nunlimited. At capacity, the vehicle has no room until it unloads, so\nthe solver may start the route with a reload at one of `reloads`."
              }
            ],
            "description": "Load already on the vehicle at shift start (pre-loaded), per\ndimension. Occupies capacity on the first trip only — flushed at the\nfirst reload — so it reduces first-trip room per dimension, enforced\nby the per-trip capacity constraint. A value above the capacity in that\ndimension is rejected with HTTP 400 (`out_of_range`). The capacity is\nresolved per dimension: the shift's capacity when it defines the\ndimension, otherwise the vehicle's. If the vehicle has a capacity map\nthat omits the dimension, the capacity is `0`; if the vehicle has no\ncapacity map and the shift does not define the dimension, it is\nunlimited. At capacity, the vehicle has no room until it unloads, so\nthe solver may start the route with a reload at one of `reloads`."
          },
          "limits": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ShiftLimits",
                "description": "Limits for this shift only. Each field set here replaces the\nvehicle's `limits` value; fields not set keep it."
              }
            ],
            "description": "Limits for this shift only. Each field set here replaces the\nvehicle's `limits` value; fields not set keep it."
          },
          "max_overtime_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum allowed overtime beyond `to` in seconds. Overtime is reached\nby working late, never by waiting: a `synchronized` or `time_lag`\nhold stops at `to`. **Default.** None: `to` is hard. Must be `>= 0`.",
            "example": 1800,
            "minimum": 0
          },
          "max_trips": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Maximum trips (depot legs) in this shift, across all reload depots.\nCounts trips, not reloads: `trips = reloads_used + 1`, where the final\nunload of `unload_before_end` is not counted. `max_trips: 1` means a\nsingle trip — reloads are permitted in `reloads` but the cap prevents\never using one, other than that final unload. `reloads` present with\n`max_trips` absent means unlimited trips. A single reload depot can only be\nrevisited up to 8 times per shift regardless of `max_trips`;\na `max_trips` beyond that against one depot\nis accepted but the extra headroom is unreachable — list more than\none reload depot to raise the practical ceiling. `0` is rejected with\nHTTP 400 (the first trip already counts as trip 1).",
            "example": 2,
            "minimum": 1
          },
          "reloads": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Depots (by `depots[].id`, each at most once) the vehicle may return to\nmid-shift to reload and start a fresh trip. Each visit takes that\ndepot's `service_duration_s` and `per_reload`. Cap trips with\n`max_trips`."
          },
          "serves_tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Hard tag scope: when set (non-empty), this shift\nserves only tasks carrying at least one of these tags. Untagged tasks\nremain serveable by every shift. Absent or empty = serves everything."
          },
          "service_factor": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Work-rate factor for this shift only. It REPLACES\n`vehicles[].service_factor` for the shift when set (absent = inherit the\nvehicle's value, which itself defaults to 1.0); a task's\n`service_factors[].factor` for this vehicle multiplies it.\n\nSame meaning, direction, and `[0.001, 5]` range as the vehicle-level\nfield: service time is DIVIDED by it, effective service time =\n`service_duration_s / service_factor`, so above `1` is faster.\n**When to use.** The same driver works at a different rate on\ndifferent days — a measured per-day efficiency, a trainee shift, a\ntwo-person crew on Fridays — instead of collapsing those days into\none vehicle-level mean.\n\nScope is identical to the vehicle-level field: task\n`service_duration_s` only, never `setup_duration_s`, depot handling\n(`depots[].service_duration_s`, `start`/`end.service_duration_s`),\nwaiting, or breaks.",
            "maximum": 5,
            "minimum": 0.001
          },
          "skills": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/VehicleSkill"
            },
            "description": "Capabilities this shift provides, replacing the vehicle's `skills`\nfor this shift only (a technician covering another region on one\nday, a crew that only carries a certification on some shifts). A\njob's `required_skills` must all appear in the skills of the shift that\nserves it, at a level of at least the job's `min_level`. Same entry\nshape as `vehicles[].skills`. Absent = the vehicle's `skills`; `[]` =\nthis shift provides none."
          },
          "start": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ShiftPlace",
                "description": "Where the shift starts. **Default.** Absent: an open start, the route\nbegins at its first task."
              }
            ],
            "description": "Where the shift starts. **Default.** Absent: an open start, the route\nbegins at its first task."
          },
          "start_at_first_task": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "When `true`, the shift starts at its first task: travel from `start`\nto the first task takes no time, so the first arrival is `from`\nplus the `start` handling, and waiting there counts from `from`.\nThat travel's distance is still charged at `per_travel_km` and reported, so\nvehicles that start closer to their work stay cheaper; its time is not\ncharged and counts toward no duration, break or leg limit.\n`free_start_travel` instead makes the travel free altogether. `true`\nwithout `start`, or together with `free_start_travel`, is rejected with\nHTTP 400 `conflicting_fields`. Default `false`.",
            "example": false
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Shift end (RFC 3339 instant, UTC offset required; hard unless `max_overtime_s` set).\n**Pitfall.** The whole route must be finished by then, the return leg\nto `end` and its depot unload included, not only the last task.",
            "example": "2026-07-01T17:00:00+02:00"
          },
          "unload_before_end": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "When `true`, a route that would end with load on board first unloads\nat one of this shift's `reloads` depots: a final `reload` stop, at the\ndepot the solver finds cheapest, taking that depot's\n`service_duration_s` and `per_reload`. It does not count toward\n`max_trips`. A route whose last trip carries no load ends without one.\n`true` without `reloads` is rejected with HTTP 400\n`conflicting_fields`. Default `false`."
          }
        },
        "additionalProperties": false,
        "example": {
          "end": {
            "location": [
              3.7174,
              51.0543
            ]
          },
          "from": "2026-07-01T08:00:00+02:00",
          "id": "mon",
          "start": {
            "location": [
              3.7174,
              51.0543
            ]
          },
          "to": "2026-07-01T17:00:00+02:00"
        }
      },
      "ShiftCosts": {
        "type": "object",
        "description": "The `Costs` fields for one shift, minus `per_used_vehicle`. A shift is one\nof a vehicle's days, so a charge for using the vehicle at all is set on the\nvehicle (or the fleet), where it applies once across its shifts. A field\nset here replaces the vehicle's value (else the fleet's) for this shift\nonly; the `Costs` schema says what each field prices.",
        "properties": {
          "min_billed_stops": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "The fewest stops this shift is billed for when used, as\n`Costs.min_billed_stops`.",
            "example": 20,
            "maximum": 20000,
            "minimum": 0
          },
          "per_drive_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour of driving on this shift, as `Costs.per_drive_hour`.",
            "example": 0.0,
            "minimum": 0
          },
          "per_overtime_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour this route finishes past the shift's `to`, as\n`Costs.per_overtime_hour`.",
            "example": 0.0,
            "minimum": 0
          },
          "per_route": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Flat charge for this used shift, as `Costs.per_route`.",
            "example": 50.0,
            "maximum": 1000000000,
            "minimum": 0
          },
          "per_route_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour of this route's wall-clock span, as `Costs.per_route_hour`.",
            "example": 35.0,
            "minimum": 0
          },
          "per_stop": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Flat charge for each stop this shift serves, as `Costs.per_stop`.",
            "example": 2.5,
            "maximum": 100000,
            "minimum": 0
          },
          "per_travel_km": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per kilometre driven on this shift, as `Costs.per_travel_km`.",
            "example": 0.2,
            "minimum": 0
          },
          "per_wait_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Per hour spent waiting for a time window to open on this shift, as\n`Costs.per_wait_hour`.",
            "example": 0.0,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "per_route": 50.0,
          "per_travel_km": 0.3
        }
      },
      "ShiftLimits": {
        "type": "object",
        "description": "Per-shift limits: the route-level `limits` fields a shift may override.\nPeriod limits apply across shifts, so they stay on the vehicle.",
        "properties": {
          "max_distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard cap on this shift's route distance, in metres. `0` to\n`2147483647`, as on the vehicle.",
            "example": 200000,
            "maximum": 2147483647,
            "minimum": 0
          },
          "max_route_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard cap on this shift's route span, in seconds. `0` to\n`2147483647`, as on the vehicle.",
            "example": 32400,
            "maximum": 2147483647,
            "minimum": 0
          },
          "max_stops": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "Maximum stops served in this shift; a job counts as one stop.\nStart, end, break and reload stops in `routes[].stops` do not count; a\nshipment counts as two stops.",
            "example": 50,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "max_stops": 12
        }
      },
      "ShiftPlace": {
        "type": "object",
        "description": "Where a shift starts or ends: exactly one of `location` or `depot`.",
        "properties": {
          "depot": {
            "type": [
              "string",
              "null"
            ],
            "description": "A `depots[].id`. Excludes `location`.",
            "example": "gent"
          },
          "location": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Place",
                "description": "An inline place. Excludes `depot`."
              }
            ],
            "description": "An inline place. Excludes `depot`."
          },
          "service_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Handling time in seconds at this end: the morning load at `start`, the\nevening unload at `end`. Overrides the depot's `service_duration_s`;\ndefault: the depot's value, or 0 for a `location` end. Not applied on\nfree travel (`free_start_travel`/`free_end_travel`). Not scaled by\n`service_factor`.\n\nThe unload must finish by the shift's `to` (or `to + max_overtime_s`):\na route whose unload would run past it is infeasible. A shift whose\nload and unload alone exceed it is rejected with HTTP 400.",
            "example": 600,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "depot": "gent"
        },
        "oneOf": [
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "location": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "location"
                  ]
                }
              ]
            },
            "required": [
              "location"
            ]
          },
          {
            "not": {
              "anyOf": [
                {
                  "properties": {
                    "depot": {
                      "type": "null"
                    }
                  },
                  "required": [
                    "depot"
                  ]
                }
              ]
            },
            "required": [
              "depot"
            ]
          }
        ]
      },
      "ShiftRef": {
        "type": "object",
        "description": "A vehicle and one of its shifts: the key of a plan route.",
        "required": [
          "vehicle",
          "shift"
        ],
        "properties": {
          "shift": {
            "type": "string",
            "description": "Shift id, within that vehicle."
          },
          "vehicle": {
            "type": "string",
            "description": "Vehicle id."
          }
        },
        "example": {
          "shift": "mon",
          "vehicle": "v2"
        }
      },
      "Shipment": {
        "type": "object",
        "description": "A bound pickup→delivery shipment (the `shipments[]` entry type).\n\nTwo stops served by one vehicle, pickup strictly before delivery, with\n`load` carried on the vehicle between the two legs.\n\n`drop_cost` and vehicle eligibility (`eligible_vehicles`, allow\n**and** exclude, any length) are fully supported and applied to both legs — a\nshipment's pickup and delivery share one droppability/eligibility decision,\nsince one vehicle must serve both.",
        "required": [
          "id",
          "pickup",
          "delivery"
        ],
        "properties": {
          "assignment_costs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/AssignmentCost"
            },
            "description": "Absolute price of serving this task on a given vehicle, in the\nobjective's currency. Charged once, when that vehicle (on any of its\nshifts) serves the task; unlisted vehicles cost nothing. Unlike\n`preferences`, which charges the vehicles that did NOT get the task,\nthis prices the vehicle that did, so a task rated badly everywhere is\nthe first one dropped when capacity runs out. It lives in the cost tier,\nbelow `priority`, and adds to `preferences`, `drop_cost` and travel.\nA request that sets it is solved as a whole rather than split into parts, which can make a large request slower."
          },
          "delivery": {
            "$ref": "#/components/schemas/ShipmentStop",
            "description": "Delivery leg (load off)."
          },
          "drop_cost": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Drop **price** — what leaving this task unserved costs you, in the same\ncurrency as `objective.costs`, and the only way to make a task\ndroppable. **Default.** Absent: the task must be served.\n\n**Pitfall.** This is money, not a priority: it enters the same cost the\nsolver minimises, so the task is served only while serving it costs\nless than dropping it. A task dropped for its price is listed in\n`unassigned[]` with `category: \"priced_out\"`. Drop costs the plan chose\nto pay are reported in `score.components.drop_costs` and summed into\n`score.cost`.\n\nOn a shipment the drop cost applies to the pair, charged once.\n\nMust be finite, `>= 0` and at most `1e9`; combined with `priority` it\nis rejected with HTTP 400 (`conflicting_fields`). Also rejected with\nHTTP 400 (`not_supported`) while a positive `objective.per_delay_workday` is set,\nsince a droppable task could be dropped to avoid its delay charge.",
            "example": 25.0,
            "maximum": 1000000000,
            "minimum": 0
          },
          "eligible_vehicles": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/VehicleEligibility",
                "description": "Hard vehicle allow/exclude. A request may use at most 256 distinct\npermitted-vehicle sets (after resolving `allowed`/`excluded`) across\nall jobs and shipments (HTTP 400 `limit_exceeded` beyond that)."
              }
            ],
            "description": "Hard vehicle allow/exclude. A request may use at most 256 distinct\npermitted-vehicle sets (after resolving `allowed`/`excluded`) across\nall jobs and shipments (HTTP 400 `limit_exceeded` beyond that)."
          },
          "id": {
            "type": "string",
            "description": "Shipment id: 1 to 128 characters, unique across `jobs` + `shipments`.",
            "example": "ship-1",
            "maxLength": 128,
            "minLength": 1
          },
          "load": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Load carried from the pickup to the delivery: picked up at one leg and\nthe same quantity dropped off at the other. Non-negative magnitudes\nper named dimension."
              }
            ],
            "description": "Load carried from the pickup to the delivery: picked up at one leg and\nthe same quantity dropped off at the other. Non-negative magnitudes\nper named dimension."
          },
          "pickup": {
            "$ref": "#/components/schemas/ShipmentStop",
            "description": "Pickup leg (load on)."
          },
          "preferences": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/VehiclePreference"
            },
            "description": "Soft vehicle affinity preferences, priced. Each entry is independent:\na job listing several preferred vehicles it doesn't get pays each\none's `violation_cost` (compounding, the same rule as a vehicle's\n`preferred_tags`)."
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Importance of a must-serve task when not all of them fit: the solver\nmaximises the summed `priority` of served tasks before any cost. `1` to\n`100000000000000` (1e14). **Default.** `1`: every task counts the same,\nso the solver serves as many as possible. **Pitfall.** A rank, not\nmoney: it never makes a task droppable; use `drop_cost` for that. Both\nset is a 400. To rank several goals at once, pack them into one value\n(see the scoring guide).",
            "example": 3,
            "maximum": 100000000000000,
            "minimum": 1
          },
          "required_skills": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/SkillRequirement"
            },
            "description": "Hard skill requirements — the assigned vehicle must provide every one,\nat or above each requirement's `min_level`. A request may use at most\n256 distinct `(name, min_level)` pairs across all jobs and shipments\n(HTTP 400 `limit_exceeded` beyond that)."
          },
          "service_factors": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/ServiceFactor"
            },
            "description": "Per-vehicle work-rate factors for this task's `service_duration_s`,\nwhich is DIVIDED by the factor (above `1` = faster). Each multiplies\nthe serving vehicle's rate (the shift's `service_factor` if set, else\nthe vehicle's): effective service time = `service_duration_s /\n(shift_or_vehicle_factor * factor)`. On a shipment the factor scales\nboth legs. A vehicle not listed works at its own rate."
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Free-form task labels (zones/territories, relation labels).\nUsed for `tag`/relation resolution and, when a shift scopes itself via\n`serves_tags` (hard ANY-overlap) or a vehicle prices them via\n`preferred_tags` (soft), for tag matching. ANY-overlap — contrast with\n`required_skills`, which requires ALL. Not capability matching on its own.\nA request may carry at most 256 distinct tags across all jobs and\nshipments (HTTP 400 `limit_exceeded` beyond that); vehicle-side tag\nlists do not count."
          },
          "target": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Target",
                "description": "Soft target for this task, measured at its arrival (default) or\ndeparture. On a shipment it is measured on the **delivery** leg and\ncannot be combined with `delivery.target` (HTTP 400\n`conflicting_fields`); `pickup.target` adds a separate target on the\npickup leg."
              }
            ],
            "description": "Soft target for this task, measured at its arrival (default) or\ndeparture. On a shipment it is measured on the **delivery** leg and\ncannot be combined with `delivery.target` (HTTP 400\n`conflicting_fields`); `pickup.target` adds a separate target on the\npickup leg."
          }
        },
        "additionalProperties": false,
        "example": {
          "delivery": {
            "location": [
              3.71,
              51.06
            ],
            "service_duration_s": 300
          },
          "id": "ship-1",
          "load": {
            "weight": 20
          },
          "pickup": {
            "location": [
              3.725,
              51.05
            ],
            "service_duration_s": 300
          }
        }
      },
      "ShipmentStop": {
        "type": "object",
        "description": "One leg of a shipment (pickup or delivery).",
        "required": [
          "location"
        ],
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stop id: 1 to 128 characters when set. Defaults to\n`\"{shipment}:pickup\"` / `\"{shipment}:delivery\"`. The effective id\n(custom or default) must be unique across all job, shipment, and stop\nids — a collision is rejected with HTTP 400.",
            "example": "ship-1:pickup",
            "maxLength": 128,
            "minLength": 1
          },
          "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).\n\nThis is the nominal figure. The serving vehicle's `service_factor`\nscales it — the time actually scheduled is\n`service_duration_s / service_factor` — so the solution's\n`stops[].service_s` may differ from what you sent here. Default `0`;\na negative value is rejected with HTTP 400.",
            "example": 300,
            "minimum": 0
          },
          "setup_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Setup time paid once on arrival at a new location (seconds),\ndistinct from `service_duration_s`. Skipped when the immediate real\npredecessor in the route already sits at this location — co-located\nstops share one setup.\n\nNot scaled by the vehicle's `service_factor`: setup is fixed arrival\noverhead (parking, walking to the door), not the work itself.\nDefault `0`; a negative value is rejected with HTTP 400.",
            "example": 60,
            "minimum": 0
          },
          "target": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Target",
                "description": "Soft target for this leg, measured at its arrival (default) or\ndeparture. Same type, units and validation as the task-level\n`target`. The shipment's own `target` is measured on the delivery\nleg, so sending it with `delivery.target` is rejected with HTTP 400\n(`conflicting_fields`)."
              }
            ],
            "description": "Soft target for this leg, measured at its arrival (default) or\ndeparture. Same type, units and validation as the task-level\n`target`. The shipment's own `target` is measured on the delivery\nleg, so sending it with `delivery.target` is rejected with HTTP 400\n(`conflicting_fields`)."
          },
          "time_windows": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/TimeWindow"
            },
            "description": "Time windows for this stop."
          }
        },
        "additionalProperties": false,
        "example": {
          "id": "ship-1:pickup",
          "location": [
            3.725,
            51.05
          ],
          "service_duration_s": 300,
          "setup_duration_s": 60,
          "time_windows": [
            {
              "from": "2026-07-01T09:00:00+02:00",
              "to": "2026-07-01T12:00:00+02:00"
            }
          ]
        }
      },
      "SkillRequirement": {
        "type": "object",
        "description": "A hard skill requirement — the assigned vehicle must provide it.",
        "required": [
          "name"
        ],
        "properties": {
          "min_level": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Minimum level the serving vehicle must hold for this skill (`>= 1`).\nAbsent = 1. A vehicle skill with no `level` holds level 1.",
            "example": 2,
            "minimum": 1
          },
          "name": {
            "type": "string",
            "description": "Skill name the assigned vehicle must provide.",
            "example": "fridge"
          }
        },
        "additionalProperties": false,
        "example": {
          "name": "fridge"
        }
      },
      "SolveOptions": {
        "type": "object",
        "description": "Solve options.",
        "properties": {
          "polyline": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PolylineDetail",
                "description": "Return road geometry for each route as `routes[].polyline`:\n`simplified` or `full`. Omitted → no geometry (the default). One value\nfor the whole request, named like the response field it fills."
              }
            ],
            "description": "Return road geometry for each route as `routes[].polyline`:\n`simplified` or `full`. Omitted → no geometry (the default). One value\nfor the whole request, named like the response field it fills."
          },
          "seed": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Random seed for the search: `0` to `9007199254740991` (2^53 − 1, the\nlargest integer JavaScript holds exactly), HTTP 400 above.\n**Default.** `42`: omitting it is the same as sending `42`, so send\ndifferent values to explore different plans. Repeated runs on one\nmachine usually return an identical plan; a materially faster or slower\nmachine can differ.",
            "default": 42,
            "example": 42,
            "maximum": 9007199254740991,
            "minimum": 0
          },
          "time_limit_s": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Upper bound on the search time in seconds, fractions allowed, building\nthe first plan included: on a large request that plan is completed\nwith a cheaper insertion once it has used half the budget (not when\nthe request has shipments: then the first plan is always built in\nfull).\n**Default.** 150 ms plus 4 ms per task (jobs and shipments combined),\nso 100 tasks search for 0.55 s. Maximum 60: a larger value is rejected\nwith HTTP 400. An async run (`POST /v3/routing/runs`) that omits it\nsearches up to 60 s plus 20 ms per task instead, and may set up to\n3600. A value below 0.1 is raised to a 100 ms floor.\n**Pitfall.** Fetching travel times and waiting for capacity are not\ndeducted from it, so the request takes longer than\nthis value. A longer search can lower `score.cost` even when every\ntask is assigned; an unassigned task with `category: \"time_limit\"` is\nthe sign that more time would also place it.",
            "example": 2.5,
            "maximum": 60,
            "minimum": 0
          },
          "travel_fallback": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TravelFallback",
                "description": "What to do when travel times cannot be fetched from Solvice Maps.\n**Default.** `estimate`: solves on estimated travel and sets\n`summary.travel_estimated`; `fail` returns the 502/503 instead.\nLocations that Maps rejects for spanning more than one region are a 400.\nNo effect with `travel.engine: \"straight_line\"`, which fetches nothing."
              }
            ],
            "description": "What to do when travel times cannot be fetched from Solvice Maps.\n**Default.** `estimate`: solves on estimated travel and sets\n`summary.travel_estimated`; `fail` returns the 502/503 instead.\nLocations that Maps rejects for spanning more than one region are a 400.\nNo effect with `travel.engine: \"straight_line\"`, which fetches nothing.",
            "default": "estimate"
          }
        },
        "additionalProperties": false,
        "example": {
          "polyline": "full",
          "seed": 42,
          "time_limit_s": 5
        }
      },
      "SolveRequest": {
        "type": "object",
        "description": "Request body for `POST /v3/routing/solve`.",
        "required": [
          "problem"
        ],
        "properties": {
          "options": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SolveOptions",
                "description": "Solve options."
              }
            ],
            "description": "Solve options."
          },
          "plan": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Plan",
                "description": "Warm start: the plan the search starts from instead of constructing\nfrom scratch (re-optimization). A result's `plan` goes in as it stands.\nSee `plan.routes[].locked_count` for freezing a dispatched prefix.\n\nA **hint, not a guarantee**: an unlocked stop that violates a hard\nconstraint (e.g. capacity, skills, eligibility, `limits.*`, or a time\nwindow with no `per_late_hour` set) is left unassigned and the\nsearch reinserts it wherever it legitimately fits, or it surfaces in\n`unassigned[]` with a typed reason. On synchronous solve and stream, an\ninfeasible locked stop is a 400. `POST /v3/routing/runs` checks the\nproblem at submission, not the plan, so there the run ends `failed`\nwith `BAD_REQUEST` instead. A pinned stop outside a `locked_count`\nprefix (a shipment leg whose other leg is inside counts as inside) is\nnever a 400 or a failed run: one that cannot be served is in\n`unassigned[]` (see `pinned`)."
              }
            ],
            "description": "Warm start: the plan the search starts from instead of constructing\nfrom scratch (re-optimization). A result's `plan` goes in as it stands.\nSee `plan.routes[].locked_count` for freezing a dispatched prefix.\n\nA **hint, not a guarantee**: an unlocked stop that violates a hard\nconstraint (e.g. capacity, skills, eligibility, `limits.*`, or a time\nwindow with no `per_late_hour` set) is left unassigned and the\nsearch reinserts it wherever it legitimately fits, or it surfaces in\n`unassigned[]` with a typed reason. On synchronous solve and stream, an\ninfeasible locked stop is a 400. `POST /v3/routing/runs` checks the\nproblem at submission, not the plan, so there the run ends `failed`\nwith `BAD_REQUEST` instead. A pinned stop outside a `locked_count`\nprefix (a shipment leg whose other leg is inside counts as inside) is\nnever a 400 or a failed run: one that cannot be served is in\n`unassigned[]` (see `pinned`)."
          },
          "problem": {
            "$ref": "#/components/schemas/Problem",
            "description": "The problem: tasks, fleet, depots, relations, objective, travel."
          }
        },
        "additionalProperties": false,
        "example": {
          "options": {
            "seed": 42,
            "time_limit_s": 5
          },
          "problem": {
            "depots": [
              {
                "id": "gent",
                "location": [
                  3.7174,
                  51.0543
                ]
              }
            ],
            "jobs": [
              {
                "id": "job-1",
                "location": [
                  3.725,
                  51.05
                ],
                "pickup_load": {
                  "weight": 20
                },
                "required_skills": [
                  {
                    "name": "fridge"
                  }
                ],
                "service_duration_s": 300,
                "time_windows": [
                  {
                    "from": "2026-07-01T09:00:00+02:00",
                    "to": "2026-07-01T12:00:00+02:00"
                  }
                ]
              },
              {
                "id": "job-2",
                "location": [
                  3.71,
                  51.06
                ],
                "pickup_load": {
                  "weight": 35
                },
                "service_duration_s": 600
              }
            ],
            "objective": {
              "costs": {
                "per_route_hour": 35.0,
                "per_travel_km": 0.2
              },
              "currency": "EUR"
            },
            "vehicles": [
              {
                "capacity": {
                  "weight": 500
                },
                "id": "v1",
                "profile": "car",
                "shifts": [
                  {
                    "end": {
                      "depot": "gent"
                    },
                    "from": "2026-07-01T08:00:00+02:00",
                    "id": "mon",
                    "start": {
                      "depot": "gent"
                    },
                    "to": "2026-07-01T17:00:00+02:00"
                  }
                ],
                "skills": [
                  {
                    "name": "fridge"
                  }
                ]
              }
            ]
          }
        }
      },
      "SolveResponse": {
        "type": "object",
        "description": "The result of `POST /v3/routing/solve` and `POST /v3/routing/evaluate`:\none shape for a plan the solver built and a plan it was given to score.",
        "required": [
          "summary",
          "routes",
          "plan",
          "unassigned",
          "warnings"
        ],
        "properties": {
          "plan": {
            "$ref": "#/components/schemas/Plan",
            "description": "The plan these routes follow, in the request's vocabulary: valid input\nto evaluate, suggest or a warm-started solve as it stands."
          },
          "routes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Route"
            },
            "description": "One entry per non-empty route."
          },
          "search_progress": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/SearchProgressPoint"
            },
            "description": "How the best plan improved during the search, oldest first: the\nstarting plan, every improvement (thinned to at most 500 entries), and\nthe final plan, which equals `summary.score` (it can equal, or be\nslightly worse than, the entry before it). Present on every solve;\nabsent on evaluate, which does not search. A large request that is\nsolved in parts has the final entry alone."
          },
          "summary": {
            "$ref": "#/components/schemas/Summary",
            "description": "Aggregate statistics for the solve run."
          },
          "unassigned": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnassignedTask"
            },
            "description": "Tasks that could not be feasibly assigned, in request order: `jobs`,\nthen `shipments`."
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestWarning"
            },
            "description": "Advisories: inputs the request carried that were adjusted or that\nchanged nothing, such as an `options.time_limit_s` below the 0.1 s\nfloor (`time_limit_raised`) or `options.travel_fallback` with\n`travel.engine: \"straight_line\"` (`no_effect`). Always present, empty\nwhen there are none; at most 100 are returned. Each item has a\n`code`, a `pointer` to the field and a `message`. Accept codes you do\nnot know. On evaluate, a `pinned` or `locked_count` in the plan is\nreported as `no_effect`, since evaluate scores the plan as listed."
          }
        },
        "example": {
          "plan": {
            "routes": [
              {
                "shift": "mon",
                "stops": [
                  {
                    "id": "job-1",
                    "type": "job"
                  },
                  {
                    "id": "job-2",
                    "type": "job"
                  }
                ],
                "vehicle": "v1"
              }
            ]
          },
          "routes": [
            {
              "distance_m": 8450,
              "load_peak": {
                "weight": 55
              },
              "shift": "mon",
              "stops": [
                {
                  "arrival": "2026-07-01T08:00:00+02:00",
                  "departure": "2026-07-01T08:00:00+02:00",
                  "depot": "gent",
                  "load_after": {
                    "weight": 0
                  },
                  "location": [
                    3.7174,
                    51.0543
                  ],
                  "service_s": 0,
                  "type": "start"
                },
                {
                  "arrival": "2026-07-01T08:10:00+02:00",
                  "departure": "2026-07-01T09:05:00+02:00",
                  "distance_m": 2600,
                  "id": "job-1",
                  "lateness_s": 0,
                  "load_after": {
                    "weight": 20
                  },
                  "location": [
                    3.725,
                    51.05
                  ],
                  "service_s": 300,
                  "service_start": "2026-07-01T09:00:00+02:00",
                  "travel_s": 600,
                  "type": "job",
                  "wait_s": 3000
                },
                {
                  "arrival": "2026-07-01T09:13:00+02:00",
                  "departure": "2026-07-01T09:23:00+02:00",
                  "distance_m": 2350,
                  "id": "job-2",
                  "lateness_s": 0,
                  "load_after": {
                    "weight": 55
                  },
                  "location": [
                    3.71,
                    51.06
                  ],
                  "service_s": 600,
                  "service_start": "2026-07-01T09:13:00+02:00",
                  "travel_s": 480,
                  "type": "job",
                  "wait_s": 0
                },
                {
                  "arrival": "2026-07-01T09:38:00+02:00",
                  "departure": "2026-07-01T09:38:00+02:00",
                  "depot": "gent",
                  "distance_m": 3500,
                  "load_after": {
                    "weight": 55
                  },
                  "location": [
                    3.7174,
                    51.0543
                  ],
                  "service_s": 0,
                  "travel_s": 900,
                  "type": "end",
                  "wait_s": 0
                }
              ],
              "time": {
                "break_s": 0,
                "depot_s": 0,
                "overtime_s": 0,
                "service_s": 900,
                "span_s": 5880,
                "travel_s": 1980,
                "wait_s": 3000
              },
              "vehicle": "v1"
            }
          ],
          "summary": {
            "distance_m": 8450,
            "score": {
              "components": {
                "assignment": 0.0,
                "delay": 0.0,
                "distance": 1.69,
                "driving": 0.0,
                "drop_costs": 0.0,
                "grouping": 0.0,
                "lateness": 0.0,
                "overtime": 0.0,
                "preferences": 0.0,
                "reloads": 0.0,
                "routes": 0.0,
                "stops": 0.0,
                "tag_preference": 0.0,
                "target": 0.0,
                "time": 57.1536,
                "vehicles": 0.0,
                "waiting": 0.0,
                "window_choice": 0.0,
                "workload_share": 0.0
              },
              "cost": 58.8436,
              "currency": "EUR",
              "unassigned_priority": 0,
              "violation_count": 0
            },
            "search": {
              "iterations": 48210,
              "termination": "time_limit"
            },
            "shifts_used": 1,
            "tasks": {
              "served": 2,
              "unassigned": 0,
              "unassigned_required": 0
            },
            "time": {
              "break_s": 0,
              "depot_s": 0,
              "overtime_s": 0,
              "service_s": 900,
              "span_s": 5880,
              "travel_s": 1980,
              "wait_s": 3000
            },
            "timings": {
              "search_ms": 100,
              "total_ms": 142
            },
            "travel_estimated": false,
            "vehicles_used": 1
          },
          "unassigned": [],
          "warnings": []
        }
      },
      "StopType": {
        "type": "string",
        "description": "The kind of a stop in a route.\n\nEvery route has one `start` and one `end`. A served job is `job`, and a\nshipment's legs are `pickup` and `delivery`. A driver break is `break`,\nand a mid-shift reload at a depot is `reload`.\n\nKnown values: `start`, `job`, `pickup`, `delivery`, `break`, `reload`, `end`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "job",
        "x-extensible-enum": [
          "start",
          "job",
          "pickup",
          "delivery",
          "break",
          "reload",
          "end"
        ]
      },
      "SuggestOptions": {
        "type": "object",
        "description": "Suggest options.",
        "properties": {
          "max_insertions": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "Max ranked `insertions` in each `suggestions[]` entry, `1` to `10`.\n**Default.** `5`. It caps the insertions per entry, not the number of\nentries: every task outside `plan` still gets its entry. Values outside\nthe range are a 400, never clamped. It also sets how widely a unit of\nseveral stops is searched (such a unit is never searched exhaustively):\neach stop after the unit's first keeps at most\n`max(8, 4 × max_insertions)` partial placements. A `synchronized` or\n`time_lag` group is the exception: every start slot of each member is\ntried, with every slot of the other member when two members are outside\n`plan` and a few slots of each other member when more are, whatever\nthis value. A\nsingle-stop task has every feasible position considered unless\n`time_limit_s` runs out first.",
            "default": 5,
            "example": 5,
            "maximum": 10,
            "minimum": 1
          },
          "time_limit_s": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Search budget in seconds, fractions allowed. **Default.** `1`;\nminimum 0.1 (smaller values are raised to it), maximum 60. The clock\nstarts when the search starts, after the matrix fetch and any wait for a\nsolver slot. Units are searched in problem order (jobs, then\nshipments), each with an equal share of the time left when it starts; a\nunit that finishes early leaves its slack to the ones after it.",
            "default": 1.0,
            "example": 2.5,
            "maximum": 60,
            "minimum": 0
          },
          "travel_fallback": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TravelFallback",
                "description": "What to do when travel times cannot be fetched from Solvice Maps, as on\na solve: `estimate` (the default) ranks insertions on estimated travel\nand sets the response's `travel_estimated`; `fail` returns the 502/503\ninstead. Locations that Maps rejects for spanning more than one region\nare a 400. No effect with `travel.engine: \"straight_line\"`."
              }
            ],
            "description": "What to do when travel times cannot be fetched from Solvice Maps, as on\na solve: `estimate` (the default) ranks insertions on estimated travel\nand sets the response's `travel_estimated`; `fail` returns the 502/503\ninstead. Locations that Maps rejects for spanning more than one region\nare a 400. No effect with `travel.engine: \"straight_line\"`.",
            "default": "estimate"
          }
        },
        "additionalProperties": false,
        "example": {
          "max_insertions": 5,
          "time_limit_s": 2
        }
      },
      "SuggestReason": {
        "type": "object",
        "description": "Why a unit came back with no insertions.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/SuggestReasonCode",
            "description": "Branch on this. Open set: accept values you do not know."
          },
          "message": {
            "type": "string",
            "description": "`code` as an English sentence, for people and logs. Do not parse it.",
            "example": "No feasible insertion position found"
          }
        },
        "example": {
          "code": "infeasible",
          "message": "No feasible insertion position found"
        }
      },
      "SuggestReasonCode": {
        "type": "string",
        "description": "Why a unit's `insertions` is empty: the machine-readable form of\n`reason`, to branch on.\n\nOpen set: values may be added within `/v3`. Accept values not listed here\nand handle them generically, for example by showing `reason.message`.\n\nKnown values: `time_limit`, `candidates_exhausted`, `infeasible`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "infeasible",
        "x-extensible-enum": [
          "time_limit",
          "candidates_exhausted",
          "infeasible"
        ]
      },
      "SuggestRequest": {
        "type": "object",
        "description": "Request body for `POST /v3/routing/suggest`.\n\nThe same body as `POST /v3/routing/evaluate`, plus optional `options`.\nGiven the committed `plan` over `problem`, ranks the feasible insertion\npositions for every task of `problem` that is not in `plan` — the tasks a\nsolve would place and an evaluate would report as unassigned. Each task\n(or unit — a shipment, or tasks tied by one `sequence`/`same_vehicle`/\n`same_day`/`same_route` relation) is ranked independently against the same\ncommitted plan; the plan is never modified.",
        "required": [
          "problem",
          "plan"
        ],
        "properties": {
          "options": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SuggestOptions",
                "description": "Suggest options. Absent: the defaults."
              }
            ],
            "description": "Suggest options. Absent: the defaults."
          },
          "plan": {
            "$ref": "#/components/schemas/Plan",
            "description": "The committed plan. Never modified, never reordered. On suggest,\n`locked_count` keeps insertions after a route's dispatched prefix."
          },
          "problem": {
            "$ref": "#/components/schemas/Problem",
            "description": "Problem definition — identical to `POST /v3/routing/solve`. Every task\nof it that is not in `plan` is a task to place."
          }
        },
        "additionalProperties": false,
        "example": {
          "options": {
            "max_insertions": 5
          },
          "plan": {
            "routes": [
              {
                "shift": "mon",
                "stops": [
                  {
                    "id": "job-1",
                    "type": "job"
                  }
                ],
                "vehicle": "v1"
              }
            ]
          },
          "problem": {
            "jobs": [
              {
                "id": "job-1",
                "location": [
                  3.725,
                  51.05
                ],
                "pickup_load": {
                  "weight": 10
                },
                "service_duration_s": 300
              },
              {
                "id": "job-2",
                "location": [
                  3.71,
                  51.06
                ],
                "pickup_load": {
                  "weight": 10
                },
                "service_duration_s": 300
              }
            ],
            "vehicles": [
              {
                "capacity": {
                  "weight": 500
                },
                "id": "v1",
                "shifts": [
                  {
                    "end": {
                      "location": [
                        3.7174,
                        51.0543
                      ]
                    },
                    "from": "2026-07-01T08:00:00+02:00",
                    "id": "mon",
                    "start": {
                      "location": [
                        3.7174,
                        51.0543
                      ]
                    },
                    "to": "2026-07-01T17:00:00+02:00"
                  }
                ]
              }
            ]
          }
        }
      },
      "SuggestResponse": {
        "type": "object",
        "description": "Response body for `POST /v3/routing/suggest`.",
        "required": [
          "suggestions",
          "truncated",
          "timings",
          "travel_estimated",
          "warnings"
        ],
        "properties": {
          "suggestions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskSuggestions"
            },
            "description": "One entry per unit of tasks outside `plan`, in problem order (jobs,\nthen shipments; a relation group sorts at its first-listed member)."
          },
          "timings": {
            "$ref": "#/components/schemas/Timings",
            "description": "Where the request's wall-clock time went. Only `total_ms` is set:\nsuggest has no separate search figure."
          },
          "travel_estimated": {
            "type": "boolean",
            "description": "`true` when travel times could not be fetched and the insertions were\nranked on estimated travel, as `summary.travel_estimated` on a solve:\nstraight-line distance × a detour factor, at a typical speed for the\nprofile. Every `delta`, arrival and feasibility verdict holds only\nagainst it. Send `options.travel_fallback: \"fail\"` to get the error\ninstead. `false` when travel came from the requested engine,\n`straight_line` included."
          },
          "truncated": {
            "type": "boolean",
            "description": "`true` when `options.time_limit_s` cut the search short, a\nmulti-member unit came back empty after the search had discarded\ncandidates (an inconclusive \"not found\"; its `reason.code` is\n`candidates_exhausted`), or a crew with three or more members outside\n`plan` lists fewer than `max_insertions` after it was refused where it\nhad left slots untried. Lists may then be incomplete or missing the best insertion. A single visit's only level is never pruned, so its\nempty list is proof of infeasibility unless the budget cut it, and its\n`reason.code` is then `time_limit`."
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestWarning"
            },
            "description": "Advisories, as on a solve response: an `options.time_limit_s` below\nthe 0.1 s floor (`time_limit_raised`), or an option that changed\nnothing (`no_effect`). Always present, empty when there are none; at\nmost 100 are returned."
          }
        },
        "example": {
          "suggestions": [
            {
              "insertions": [
                {
                  "delta": {
                    "cost": 12.4,
                    "distance_m": 2400,
                    "travel_s": 240
                  },
                  "placements": [
                    {
                      "arrival": "2026-07-01T09:30:00+02:00",
                      "id": "job-2",
                      "latest_arrival": "2026-07-01T10:15:00+02:00",
                      "service_start": "2026-07-01T09:30:00+02:00",
                      "shift": "mon",
                      "type": "job",
                      "vehicle": "v1"
                    }
                  ],
                  "routes": [
                    {
                      "shift": "mon",
                      "stops": [
                        {
                          "id": "job-1",
                          "type": "job"
                        },
                        {
                          "id": "job-2",
                          "type": "job"
                        }
                      ],
                      "vehicle": "v1"
                    }
                  ]
                }
              ],
              "task": "job-2"
            }
          ],
          "timings": {
            "total_ms": 8
          },
          "travel_estimated": false,
          "truncated": false,
          "warnings": []
        }
      },
      "Summary": {
        "type": "object",
        "description": "The plan in numbers: its score, what it serves and what it takes.",
        "required": [
          "score",
          "tasks",
          "vehicles_used",
          "shifts_used",
          "distance_m",
          "time",
          "timings",
          "search",
          "travel_estimated"
        ],
        "properties": {
          "distance_m": {
            "type": "integer",
            "format": "int64",
            "description": "Sum of all route distances, in metres.",
            "example": 8450
          },
          "score": {
            "$ref": "#/components/schemas/Score",
            "description": "How good the plan is. On `/solve`, `score.violation_count` is 0 unless a\n`pinned` plan stop forces a relation breach, counted as `/evaluate` counts it; on\n`/evaluate` it counts the constraints the given plan breaks."
          },
          "search": {
            "$ref": "#/components/schemas/SearchInfo",
            "description": "How the search ended."
          },
          "shifts_used": {
            "type": "integer",
            "format": "uint32",
            "description": "Routes with at least one task stop: one per used shift.",
            "example": 1,
            "minimum": 0
          },
          "tasks": {
            "$ref": "#/components/schemas/TaskCounts",
            "description": "Tasks served and left out."
          },
          "time": {
            "$ref": "#/components/schemas/TimeTotals",
            "description": "Where the fleet's time goes, summed over routes."
          },
          "timings": {
            "$ref": "#/components/schemas/Timings",
            "description": "Where the request's time went."
          },
          "travel_estimated": {
            "type": "boolean",
            "description": "`true` when travel times could not be fetched and the plan was costed\non estimated travel: straight-line distance × a detour factor, at a\ntypical speed for the profile. No one-way streets or traffic, so it\ncan be tens of percent off: the plan, `unassigned[].reasons` and\n`score.violation_count` hold only against it, and no `routes[].polyline`\nis returned. Solve again once Maps is back if the plan must hold on the\nroad; on a solve or suggest, `options.travel_fallback: \"fail\"` returns\nthe error instead. `false` when travel came from the requested engine,\n`straight_line` included."
          },
          "vehicles_used": {
            "type": "integer",
            "format": "uint32",
            "description": "Distinct vehicles with at least one route.",
            "example": 1,
            "minimum": 0
          }
        },
        "example": {
          "distance_m": 8450,
          "score": {
            "components": {
              "assignment": 0.0,
              "delay": 0.0,
              "distance": 1.69,
              "driving": 0.0,
              "drop_costs": 0.0,
              "grouping": 0.0,
              "lateness": 0.0,
              "overtime": 0.0,
              "preferences": 0.0,
              "reloads": 0.0,
              "routes": 0.0,
              "stops": 0.0,
              "tag_preference": 0.0,
              "target": 0.0,
              "time": 57.1536,
              "vehicles": 0.0,
              "waiting": 0.0,
              "window_choice": 0.0,
              "workload_share": 0.0
            },
            "cost": 58.8436,
            "currency": "EUR",
            "unassigned_priority": 0,
            "violation_count": 0
          },
          "search": {
            "iterations": 48210,
            "termination": "time_limit"
          },
          "shifts_used": 1,
          "tasks": {
            "served": 2,
            "unassigned": 0,
            "unassigned_required": 0
          },
          "time": {
            "break_s": 0,
            "depot_s": 0,
            "overtime_s": 0,
            "service_s": 900,
            "span_s": 5880,
            "travel_s": 1980,
            "wait_s": 3000
          },
          "timings": {
            "search_ms": 100,
            "total_ms": 142
          },
          "travel_estimated": false,
          "vehicles_used": 1
        }
      },
      "TagPreference": {
        "type": "object",
        "description": "A soft tag preference, priced.",
        "required": [
          "tag",
          "violation_cost"
        ],
        "properties": {
          "tag": {
            "type": "string",
            "description": "Preferred tag.",
            "example": "north"
          },
          "violation_cost": {
            "type": "number",
            "format": "double",
            "description": "Cost, in the objective's currency, incurred when a task without this\ntag is served. Must be finite and `>= 0`, and one vehicle's entries\nmust sum to at most 21474.83647 (a task lacking every tag pays them all).",
            "example": 25.0,
            "maximum": 21474.83647,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "tag": "north",
          "violation_cost": 25.0
        }
      },
      "Target": {
        "type": "object",
        "description": "Soft target: reaching the task's `on` instant after `at` is allowed but\npriced. Distinct from a hard time window — a target is a point, never\ncauses infeasibility, and (unlike a window's `from`) never forces the\nvehicle to wait when it is early.",
        "required": [
          "at",
          "per_late_hour"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "Target instant (RFC 3339, UTC offset required) the `on` instant is measured against.",
            "example": "2026-07-01T10:00:00+02:00"
          },
          "on": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TargetInstant",
                "description": "Which instant of the task is compared to `at`: `arrival` (default) or\n`departure`, the stop fields of the same names."
              }
            ],
            "description": "Which instant of the task is compared to `at`: `arrival` (default) or\n`departure`, the stop fields of the same names.",
            "default": "arrival"
          },
          "per_late_hour": {
            "type": "number",
            "format": "double",
            "description": "Cost, in the objective's currency, per hour of `on` beyond `at`\n(linear, prorated per second). Must be `> 0`; independent of\n`objective.per_late_hour` (which prices *time-window* lateness,\nnot a target point).",
            "example": 60.0,
            "maximum": 21474.83647,
            "minimum": 1e-05
          }
        },
        "additionalProperties": false,
        "example": {
          "at": "2026-07-01T10:00:00+02:00",
          "on": "arrival",
          "per_late_hour": 60.0
        }
      },
      "TargetInstant": {
        "type": "string",
        "description": "Which instant of a task a `target` is measured at, named after the\nresponse stop field that reports it.",
        "enum": [
          "arrival",
          "departure"
        ]
      },
      "TaskCounts": {
        "type": "object",
        "description": "How many tasks the plan serves. A job is one task; a shipment (pickup\nplus delivery) is one task.",
        "required": [
          "served",
          "unassigned",
          "unassigned_required"
        ],
        "properties": {
          "served": {
            "type": "integer",
            "format": "uint32",
            "description": "Tasks on a route.",
            "minimum": 0
          },
          "unassigned": {
            "type": "integer",
            "format": "uint32",
            "description": "Tasks on no route: the length of `unassigned`.",
            "minimum": 0
          },
          "unassigned_required": {
            "type": "integer",
            "format": "uint32",
            "description": "The unassigned tasks that carry no `drop_cost`: tasks the plan was\nrequired to serve and did not.",
            "minimum": 0
          }
        },
        "example": {
          "served": 2,
          "unassigned": 0,
          "unassigned_required": 0
        }
      },
      "TaskSuggestions": {
        "type": "object",
        "description": "Ranked insertion suggestions for a single unit.",
        "required": [
          "task",
          "insertions"
        ],
        "properties": {
          "insertions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InsertionOption"
            },
            "description": "Ranked feasible insertions, lowest `delta.cost` first. Empty if none\nwas found; `reason` then says why. Known limitation: suggest never\nopens a **new reload trip** on a multi-trip vehicle."
          },
          "reason": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SuggestReason",
                "description": "Why `insertions` is empty; absent otherwise."
              }
            ],
            "description": "Why `insertions` is empty; absent otherwise."
          },
          "task": {
            "type": "string",
            "description": "The unit's lead: the visit, the shipment, the first stop of a\n`sequence` chain in the unit, or else, a crew included, the member\nthat comes first in problem order (`jobs`, then `shipments`).",
            "example": "job-2"
          }
        },
        "example": {
          "insertions": [
            {
              "delta": {
                "cost": 12.4,
                "distance_m": 2400,
                "travel_s": 240
              },
              "placements": [
                {
                  "arrival": "2026-07-01T09:30:00+02:00",
                  "id": "job-2",
                  "latest_arrival": "2026-07-01T10:15:00+02:00",
                  "service_start": "2026-07-01T09:30:00+02:00",
                  "shift": "mon",
                  "type": "job",
                  "vehicle": "v1"
                }
              ],
              "routes": [
                {
                  "shift": "mon",
                  "stops": [
                    {
                      "id": "job-1",
                      "type": "job"
                    },
                    {
                      "id": "job-2",
                      "type": "job"
                    }
                  ],
                  "vehicle": "v1"
                }
              ]
            }
          ],
          "task": "job-2"
        }
      },
      "TimeLagMember": {
        "type": "object",
        "description": "One end of a `time_lag` relation.",
        "required": [
          "stop"
        ],
        "properties": {
          "on": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/RelationInstant",
                "description": "Which instant of the job the bound is measured at: `service_start`\n(default) or `departure`, the stop fields of the same names."
              }
            ],
            "description": "Which instant of the job the bound is measured at: `service_start`\n(default) or `departure`, the stop fields of the same names.",
            "default": "service_start"
          },
          "stop": {
            "type": "string",
            "description": "The stop: a job id. A shipment's own id or a shipment-leg stop id is\nrejected with HTTP 400.",
            "example": "job-1"
          }
        },
        "additionalProperties": false,
        "example": {
          "on": "departure",
          "stop": "job-1"
        }
      },
      "TimeTotals": {
        "type": "object",
        "description": "Where a route's time goes, in seconds. On the summary: the sum over\nroutes.\n\n`span_s` is the wall-clock span, from the start stop's `arrival` to the\nend stop's `departure`; it is what `per_route_hour` is charged on. The\nother fields break it down and sum to `span_s`, with two exceptions:\nsetup time (`setup_duration_s`) is inside the span with no field of its\nown, and a `fixed` break that begins while the vehicle is driving\noverlaps that drive: the overlap is in both `travel_s` and `break_s`, so\non such a route the parts can exceed `span_s`.",
        "required": [
          "span_s",
          "travel_s",
          "service_s",
          "depot_s",
          "wait_s",
          "break_s",
          "overtime_s"
        ],
        "properties": {
          "break_s": {
            "type": "integer",
            "format": "int64",
            "description": "Time on driver breaks: the `break` stops plus the breaks that paused\na job's service (the job stops' `break_s`)."
          },
          "depot_s": {
            "type": "integer",
            "format": "int64",
            "description": "Handling time at start, end and reload stops."
          },
          "overtime_s": {
            "type": "integer",
            "format": "int64",
            "description": "The part of the span after the shift's `to` (possible only with\n`max_overtime_s`)."
          },
          "service_s": {
            "type": "integer",
            "format": "int64",
            "description": "On-site service time at job, pickup and delivery stops."
          },
          "span_s": {
            "type": "integer",
            "format": "int64",
            "description": "Wall-clock span: travel, service, setup, depot handling, waiting and\nbreaks."
          },
          "travel_s": {
            "type": "integer",
            "format": "int64",
            "description": "Driving time: the sum of the stops' `travel_s`."
          },
          "wait_s": {
            "type": "integer",
            "format": "int64",
            "description": "Waiting before service, cross-route holds included, plus the idle\nbefore a windowed break's window opens, at any stop. It is the sum of\nthe stops' `wait_s`, so it can exceed `score.components.waiting` and\nwhat `per_wait_hour` charges for: that idle is priced only through\nthe span."
          }
        },
        "example": {
          "break_s": 0,
          "depot_s": 0,
          "overtime_s": 0,
          "service_s": 900,
          "span_s": 5880,
          "travel_s": 1980,
          "wait_s": 3000
        }
      },
      "TimeWindow": {
        "type": "object",
        "description": "A time window. Hard unless it (or `objective.per_late_hour`, for\nevery window) prices lateness.",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "choice_cost": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Optional flat cost, in the objective's currency, added when this\njob/stop is served within THIS window rather than a free/cheaper\nalternative window on the same task. **When to use.** A task with\nseveral acceptable windows where some are preferred: the plan may use\nany of them, and pays this amount when it uses this one. **Default.**\nAbsent = 0 (no charge). Every\nwindow in the list remains individually hard — a job must still land\nin *some* window — this only grades preference among the hard\nalternatives; it does not soften time-window feasibility. Must be\nfinite and `>= 0`, and requires at least 2 windows on the task. Once\nany window on the task carries a *nonzero* cost, that task's windows\nmust also be pairwise non-overlapping, and windows that only touch\ncount as overlapping (a task whose costs are all\n`0`/absent has its overlapping windows merged).\n\n**Pitfall.** Cannot be combined with `objective.per_late_hour > 0`: a\nnonzero `choice_cost` anywhere in the request alongside priced lateness\nis rejected with HTTP 400 (the two read opposite ways about which\nwindow was paid for). Choose one: priced alternative windows, or priced\nlateness.",
            "maximum": 21474.83647,
            "minimum": 0
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "Earliest allowed start of service (RFC 3339 instant, UTC offset\nrequired). A vehicle that arrives earlier waits. **Pitfall.** A\ntimestamp without a UTC offset or `Z` is rejected with HTTP 400 that\nnames the field.",
            "example": "2026-07-01T09:00:00+02:00"
          },
          "per_late_hour": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Makes this window soft on its late side: arriving after `to` is\nallowed and priced at this rate, in the objective's currency per hour\nlate, in place of `objective.per_late_hour` (and whether or not\nthat is set). **When to use.** Hard and soft windows in one request:\nset it on the tasks that may run late and leave the others hard. Must be\n`> 0`; omit it for a hard window. Only on a\ntask with exactly one window. Arriving early still waits for `from`.",
            "example": 60.0,
            "minimum": 0.0006
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "Latest allowed start of service (RFC 3339 instant, UTC offset\nrequired). Service starts after any windowed break taken on arrival.\nHard unless `per_late_hour` prices lateness. **Pitfall.** The window\nbounds the start of service, not its end: a windowed break taken on\narrival that pushes the start past `to` misses the window.",
            "example": "2026-07-01T12:00:00+02:00"
          }
        },
        "additionalProperties": false,
        "example": {
          "choice_cost": 15.0,
          "from": "2026-07-01T09:00:00+02:00",
          "to": "2026-07-01T12:00:00+02:00"
        }
      },
      "Timings": {
        "type": "object",
        "description": "Where the request's wall-clock time went, in milliseconds.",
        "required": [
          "total_ms"
        ],
        "properties": {
          "search_ms": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint64",
            "description": "Time spent in the search, building the first plan included. Absent on\n`/evaluate`, which runs none, and on `/suggest`, which has no separate\nsearch figure.",
            "minimum": 0
          },
          "total_ms": {
            "type": "integer",
            "format": "uint64",
            "description": "From the request's arrival to the end of the search (of the scoring,\non `/evaluate`; of the suggestion search, on `/suggest`): fetching\ntravel times and waiting for capacity included, building the response\nnot.",
            "minimum": 0
          }
        },
        "example": {
          "search_ms": 100,
          "total_ms": 142
        }
      },
      "Travel": {
        "type": "object",
        "description": "Where travel times and distances come from.\n\nOmitted altogether, travel times are free-flow (`osm`): the same request\nprices the same at any hour. Set `departure_time` to plan against an\ninstant's traffic — e.g. tomorrow's 08:00 routes with morning-rush travel\ntimes, or a replay of a past run under its original conditions; the engine\nis then `tomtom`. Set `engine: tomtom` alone for traffic at the moment the\nrequest is processed. `engine: \"straight_line\"` skips the road network for\ngreat-circle travel at `speed_kmh`.",
        "properties": {
          "departure_time": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Departure time for the traffic lookup (RFC 3339 instant, any offset).\n**Default.** Omitted: free-flow times, or traffic at solve time with\n`engine: tomtom`. **Pitfall.** Rejected with HTTP 400 alongside\n`engine: osm` or `engine: straight_line`, and an explicit departure\ntime bypasses the server-side matrix cache, so every such request\nfetches fresh travel data.",
            "example": "2026-07-01T08:00:00+02:00"
          },
          "engine": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MatrixEngine",
                "description": "Data behind travel times and distances. **Default.** Omitted: `osm`\n(free-flow times), or `tomtom` when `departure_time` is set or `time_dependent` is `true`.\n**When to use.** `tomtom` with a `departure_time` to plan against that\ninstant's traffic; `straight_line` to skip the road network altogether\nand price great-circle travel at `speed_kmh`."
              }
            ],
            "description": "Data behind travel times and distances. **Default.** Omitted: `osm`\n(free-flow times), or `tomtom` when `departure_time` is set or `time_dependent` is `true`.\n**When to use.** `tomtom` with a `departure_time` to plan against that\ninstant's traffic; `straight_line` to skip the road network altogether\nand price great-circle travel at `speed_kmh`."
          },
          "speed_kmh": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Travel speed for `engine: \"straight_line\"`, in km/h: each leg takes its\ngreat-circle distance at this speed, rounded to the whole second. `1` to\n`1000`. **Default.** `50`; `vehicles[].speed_factor` still scales it per\nvehicle. Any other engine rejects it (HTTP 400 `conflicting_fields`).",
            "default": 50.0,
            "example": 50,
            "maximum": 1000,
            "minimum": 1
          },
          "time_dependent": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Price each leg at the time of day it is driven, instead of at one\ninstant. Solvice Maps prices traffic in six slices of the day, starting at\n06:30, 09:30, 12:00, 14:30, 16:30 and 19:30 UTC (weekday and weekend differ);\nthe solver fits a smooth curve through them per location pair, so a leg\nthat starts at 08:10 costs what 08:10 costs, not what the whole day\ncosts. Default `false`.\n\nImplies `engine: tomtom`. Rejected with HTTP 400 `conflicting_fields`\nalongside `departure_time` (the shifts already say which day to price),\nany other engine, or a vehicle `profile` other than `car`. Costs six\nmatrix fetches per day type the shifts cover and bypasses the matrix\ncache. At most 500 distinct locations (400 `limit_exceeded`). Not enabled\nby default: 403 `feature_not_enabled`.\n\nThe slice schedule is UTC, like Solvice Maps: in Brussels the\nmorning-rush slice is 07:30–10:30 local in winter and 08:30–11:30 in\nsummer. A shift is priced with the weekday or weekend curves from the\nUTC date of each leg's start."
          }
        },
        "additionalProperties": false,
        "example": {
          "departure_time": "2026-07-01T08:00:00+02:00",
          "engine": "tomtom"
        }
      },
      "TravelFallback": {
        "type": "string",
        "description": "`options.travel_fallback`: what a solve or suggest does when travel times\ncannot be fetched. `/evaluate` always estimates.",
        "enum": [
          "estimate",
          "fail"
        ],
        "example": "estimate"
      },
      "TriggerAfter": {
        "type": "string",
        "description": "What a break trigger accumulates since the last break: `drive` counts\ndriving time only; `duty` counts travel, service and setup time, but not\nwaiting (for a time window to open or for a coupled task).",
        "enum": [
          "drive",
          "duty"
        ],
        "example": "drive"
      },
      "UnassignedCategory": {
        "type": "string",
        "description": "Which kind of \"unassigned\" a task is.\n\nKnown values: `impossible`, `blocked`, `priced_out`, `time_limit`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "example": "priced_out",
        "x-extensible-enum": [
          "impossible",
          "blocked",
          "priced_out",
          "time_limit"
        ]
      },
      "UnassignedReason": {
        "type": "object",
        "description": "A machine-readable reason a task could not be assigned: the\n`constraint` to blame, when one is, and a sentence.",
        "required": [
          "message"
        ],
        "properties": {
          "constraint": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ConstraintCode",
                "description": "The constraint that refused the task on at least one vehicle (or\n`all_or_none`, for a task its group holds back), in the vocabulary of\nthe evaluate violations' `code`. A task lists one reason\nper constraint, once each, in the order the `code` values are listed. Absent on the\nsingle reason of a `time_limit` or `priced_out` task, which names no\nconstraint, unless `all_or_none` is among its reasons."
              }
            ],
            "description": "The constraint that refused the task on at least one vehicle (or\n`all_or_none`, for a task its group holds back), in the vocabulary of\nthe evaluate violations' `code`. A task lists one reason\nper constraint, once each, in the order the `code` values are listed. Absent on the\nsingle reason of a `time_limit` or `priced_out` task, which names no\nconstraint, unless `all_or_none` is among its reasons."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation.",
            "example": "A route cannot reach this task within its time window"
          }
        },
        "example": {
          "constraint": "time_window",
          "message": "A route cannot reach this task within its time window"
        }
      },
      "UnassignedTask": {
        "type": "object",
        "description": "A task the plan leaves unassigned.",
        "required": [
          "task",
          "category",
          "reasons",
          "relaxations"
        ],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/UnassignedCategory",
            "description": "Which kind of \"unassigned\" this is."
          },
          "reasons": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnassignedReason"
            },
            "description": "Never empty. When `category` is `impossible` or `blocked` there is\none reason per constraint that refused the task on at least one\nvehicle, named in `constraint`, once each, `unreachable` first\n(`unknown` when no constraint was recorded). A vehicle that lacks a\nrequired skill or a tag it does not serve, or that `eligible_vehicles`\nrules out, counts for that alone, not also counted for its shifts' hours\n(`time_window`, `shift_end`). An `impossible` or `blocked` task\nwhose `all_or_none` group holds it back has the one reason\n`all_or_none`. A `time_limit` task whose group did not fit whole names\n`all_or_none` and the constraints that refused the member left over.\nOne whose all-or-none `synchronized`/`time_lag`\ngroup cannot be placed together has `synchronized` and/or `time_lag`.\nOtherwise there is one reason with no `constraint`."
          },
          "relaxations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Relaxation"
            },
            "description": "Best-effort, actionable relaxation suggestions. Empty when no simple\nrelaxation exists (e.g. a skills mismatch)."
          },
          "task": {
            "type": "string",
            "description": "The unassigned task: a job id or a shipment id.",
            "example": "job-2"
          }
        },
        "example": {
          "category": "blocked",
          "reasons": [
            {
              "constraint": "time_window",
              "message": "A route cannot reach this task within its time window"
            }
          ],
          "relaxations": [
            {
              "amount": 900,
              "message": "Extend a time window by 900s (~15 min).",
              "op": "extend_time_window",
              "pointer": "/problem/jobs/1/time_windows",
              "unit": "s"
            }
          ],
          "task": "job-2"
        }
      },
      "ValidateResponse": {
        "type": "object",
        "description": "The 200 body of `POST /v3/routing/validate/{solve,evaluate,suggest}`: the\nrequest passed every check a real call runs before the matrix fetch.",
        "required": [
          "valid",
          "warnings"
        ],
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Always `true`: an invalid request gets a 400 instead."
          },
          "warnings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestWarning"
            },
            "description": "The advisories the real call would return in its own `warnings[]`,\nas far as they need no travel data: an `options.time_limit_s` below\nthe floor, an option that has no effect with the request's travel\nengine, plan flags evaluate ignores. Empty when there are none."
          }
        },
        "example": {
          "valid": true,
          "warnings": []
        }
      },
      "Vehicle": {
        "type": "object",
        "description": "A vehicle available to serve tasks.",
        "required": [
          "id",
          "shifts"
        ],
        "properties": {
          "capacity": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Quantities",
                "description": "Named capacity dimensions, matched by name against the tasks'\n`pickup_load`, `delivery_load` and `load`. **Default.** Absent: no load\nlimit in any dimension. **Pitfall.** A dimension not named here has\ncapacity `0`, and a mismatched name is not an error: a task demanding\na dimension this vehicle does not name can never ride it, and `{}`\ncarries nothing at all. To mean \"no limit\", omit the field."
              }
            ],
            "description": "Named capacity dimensions, matched by name against the tasks'\n`pickup_load`, `delivery_load` and `load`. **Default.** Absent: no load\nlimit in any dimension. **Pitfall.** A dimension not named here has\ncapacity `0`, and a mismatched name is not an error: a task demanding\na dimension this vehicle does not name can never ride it, and `{}`\ncarries nothing at all. To mean \"no limit\", omit the field."
          },
          "compatible_with": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Vehicles this one may serve a `compatible_vehicles` relation's tasks\ntogether with, by id. Absent: any vehicle. A list is a veto, so a\none-sided list still binds both vehicles: two vehicles may share a\nrelation only if neither's list excludes the other. A vehicle always\npairs with itself and all its shifts count as one vehicle; to pair a\nvehicle with no other, list only its own id. An empty list is rejected\nwith HTTP 400 (it would read as \"everyone\" in a client that drops empty\narrays), and so is an id that names no vehicle. Inert unless a\n`compatible_vehicles` relation names tasks.",
            "example": [
              "v2",
              "v3"
            ],
            "minItems": 1
          },
          "costs": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Costs",
                "description": "This vehicle's costs. Each field set here replaces the same field of\n`objective.costs` for this vehicle; fields not set keep the fleet\nvalue. A shift's own `costs` replace these per field in turn."
              }
            ],
            "description": "This vehicle's costs. Each field set here replaces the same field of\n`objective.costs` for this vehicle; fields not set keep the fleet\nvalue. A shift's own `costs` replace these per field in turn."
          },
          "id": {
            "type": "string",
            "description": "Vehicle id: 1 to 128 characters, unique across `vehicles[]`; echoed as\n`routes[].vehicle`.",
            "example": "v1",
            "maxLength": 128,
            "minLength": 1
          },
          "limits": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/VehicleLimits",
                "description": "Hard operating limits."
              }
            ],
            "description": "Hard operating limits."
          },
          "load_compatibility": {
            "type": [
              "object",
              "null"
            ],
            "description": "Which capacity dimensions may be on board together, for vehicles that\nkeep streams apart (waste fractions, hazardous goods).\n`load_compatibility[a][b] = v` means: while dimension `a` has load on\nboard (more than 0), dimension `b` holds at most `v`. With several\ndimensions on board, the smallest such `v` applies, and `capacity`\nstill applies on top. With `v = 0` the pair is mutually exclusive in\neither order, so one cell is enough; a larger `v` allows a little of\n`b` beside `a` and is one-way: list `[b][a]` as well to cap `a` beside\n`b`. A pair left out is unrestricted.\n\nChecked after every stop, trip by trip: a `reload` empties the vehicle,\nso each trip starts free, and unloading one stream before loading the\nnext is fine. A shift's `initial_load`, and the stock a task's\n`delivery_load` carries from the depot, count as on board from the\nfirst trip's start; a reload clears them. Every name must be a dimension of this vehicle's\n`capacity` (a shift's `capacity` override does not add one; declare it\non the vehicle, with a large value for no limit); a dimension never\nlists itself (use `capacity`). Values must be 0 or more; a cap at or\nabove `capacity` restricts nothing. A task whose own load breaks the\nrule on every vehicle stays unassigned.",
            "additionalProperties": {
              "$ref": "#/components/schemas/Quantities"
            },
            "propertyNames": {
              "type": "string"
            },
            "example": {
              "general": {
                "paper": 0,
                "recycling": 0
              },
              "recycling": {
                "paper": 0
              }
            }
          },
          "preferred_tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/TagPreference"
            },
            "description": "Soft tag preferences. Serving a task that does not\ncarry a preferred tag incurs that entry's `violation_cost`. Entries\napply independently: a task lacking several preferred tags incurs each\ncost."
          },
          "profile": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Profile",
                "description": "Routing profile: `car`, `truck` or `bike` — selects the road\nnetwork and speeds behind this vehicle's travel times and distances.\n**Default.** `car`. Any other value is rejected with HTTP 400."
              }
            ],
            "description": "Routing profile: `car`, `truck` or `bike` — selects the road\nnetwork and speeds behind this vehicle's travel times and distances.\n**Default.** `car`. Any other value is rejected with HTTP 400."
          },
          "service_factor": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Work-rate multiplier for service time at stops (1.0 = base rate).\n\nSame direction as `speed_factor`: effective service time =\n`service_duration_s / service_factor`, so values > 1.0 model a driver who\nworks FASTER and spends less time at each stop, and < 1.0 one who is\nslower. Use it for crew size, equipment, or experience — how quickly the\nwork gets done, as distinct from how fast the vehicle drives.\n\nApplies to job/stop `service_duration_s` only. Deliberately NOT applied\nto `setup_duration_s` (fixed arrival overhead such as parking),\ndepot handling (`depots[].service_duration_s`,\n`start`/`end.service_duration_s`), waiting time, or break durations.\n\nMust be in `[0.001, 5]`. Default 1.0. A shift's own `service_factor`\nreplaces it for that shift; a task's `service_factors[].factor` for\nthis vehicle multiplies whichever applies: effective service time =\n`service_duration_s / (shift_or_vehicle_factor * task_factor)`.\n\nMigrating from V2: `durationModifier` went the other way (it multiplied\nduration, `0.8` = 20% faster), so send `1 / durationModifier` as the\ntask's `service_factors[].factor`.",
            "default": 1.0,
            "maximum": 5,
            "minimum": 0.001
          },
          "shifts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shift"
            },
            "description": "One or more working shifts. A vehicle without shifts is rejected with\nHTTP 400.",
            "minItems": 1
          },
          "skills": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/VehicleSkill"
            },
            "description": "Capabilities the vehicle provides. A job's `required_skills` must all appear\nhere at a level of at least the job's `min_level`. Each entry is an\nobject `{ \"name\": ..., \"level\": N }` (`level` optional, default 1);\na bare string is rejected. A skill may appear once per list.\n**Pitfall.** Omitting the field is the same as `[]`: the vehicle can\nonly serve jobs that require no skills."
          },
          "speed_factor": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Travel-speed multiplier (1.0 = base speed). Effective travel time =\n`base travel time / speed_factor`, so values > 1.0 model a faster\nvehicle and < 1.0 a slower one. Must be in `[0.001, 5]`. Default 1.0.\n\nCovers driving only. Its companion `service_factor` scales the\nwork done at stops; the two are independent and share this direction and\nrange.",
            "default": 1.0,
            "maximum": 5,
            "minimum": 0.001
          },
          "workload_weight": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Share of the work this vehicle carries under `objective.workload_share`,\nrelative to the other vehicles. Default `1`; `0.5` carries half as much;\n`0` leaves the vehicle out of the balancing. `0` to `1000000`\n(HTTP 400 `out_of_range` outside that). Ignored when\n`objective.workload_share` is not set.",
            "example": 0.5,
            "maximum": 1000000,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "capacity": {
            "volume": 20,
            "weight": 500
          },
          "id": "v1",
          "profile": "car",
          "shifts": [
            {
              "end": {
                "location": [
                  3.7174,
                  51.0543
                ]
              },
              "from": "2026-07-01T08:00:00+02:00",
              "id": "mon",
              "start": {
                "location": [
                  3.7174,
                  51.0543
                ]
              },
              "to": "2026-07-01T17:00:00+02:00"
            }
          ],
          "skills": [
            {
              "name": "fridge"
            }
          ]
        }
      },
      "VehicleEligibility": {
        "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. **Default.** Omitted: every vehicle is\nallowed. An empty list, or an id that names no vehicle, is rejected\nwith HTTP 400. **Pitfall.** A one-vehicle list does not make the task\nmust-serve: a task restricted this way that does not fit still comes\nback in `unassigned[]`, and pays its `drop_cost` if it has one.",
            "minItems": 1
          },
          "excluded": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Hard blacklist of vehicle ids. Mutually exclusive with `allowed`. An\nid that names no vehicle is rejected with HTTP 400."
          }
        },
        "additionalProperties": false,
        "example": {
          "allowed": [
            "v1",
            "v2"
          ]
        },
        "not": {
          "not": {
            "anyOf": [
              {
                "properties": {
                  "allowed": {
                    "type": "null"
                  }
                },
                "required": [
                  "allowed"
                ]
              },
              {
                "properties": {
                  "excluded": {
                    "type": "null"
                  }
                },
                "required": [
                  "excluded"
                ]
              }
            ]
          },
          "required": [
            "allowed",
            "excluded"
          ]
        }
      },
      "VehicleLimits": {
        "type": "object",
        "description": "Vehicle distance/time limits.",
        "properties": {
          "max_distance_m": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard maximum distance in metres. `0` to `2147483647`; a value\noutside that range is rejected with HTTP 400 `out_of_range`.",
            "example": 200000,
            "maximum": 2147483647,
            "minimum": 0
          },
          "max_leg_travel_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard cap in seconds on any single travel leg of this vehicle's routes:\nthe `travel_s` reported on each stop, start-to-first-task and\nlast-task-to-`end` included. Travel only: setup, service and wait do\nnot count, and `speed_factor` applies first. A leg made free by\n`free_start_travel`/`free_end_travel`, or absent on an open start or\nend, is exempt. Absent = no cap. Must be > 0: `0` would make every\nleg too long rather than mean \"no cap\", so it is rejected with HTTP\n400 `out_of_range`, as is a value above 2,147,483,647. A\nbreach is reported as `max_leg_travel`.",
            "example": 3600,
            "maximum": 2147483647,
            "minimum": 1
          },
          "max_route_duration_s": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Hard maximum route duration in seconds: the whole-route span —\ntravel, service, and wait all count, depot load and unload included.\nThe same quantity as the response's `routes[].time.span_s`. `0` to\n`2147483647`; a value outside that range is rejected with HTTP 400\n`out_of_range`.",
            "example": 32400,
            "maximum": 2147483647,
            "minimum": 0
          },
          "max_stops": {
            "type": [
              "integer",
              "null"
            ],
            "format": "uint32",
            "description": "Maximum stops served per shift; a job counts as one stop.\nStart, end, break and reload stops in `routes[].stops` do not count; a\nshipment counts as two stops.",
            "example": 50,
            "minimum": 0
          },
          "periods": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PeriodLimit"
            },
            "description": "Hard caps on this vehicle's totals across all of its shifts in a day,\na week or an explicit window. Each shift counts toward the one\nperiod that contains its `from`, read in that shift's own UTC offset.\nA recurring period with none of the vehicle's shifts is skipped; an\nexplicit window with no shift start is a 400."
          }
        },
        "additionalProperties": false,
        "example": {
          "max_distance_m": 200000,
          "max_route_duration_s": 32400
        }
      },
      "VehiclePreference": {
        "type": "object",
        "description": "A soft vehicle affinity preference, priced.",
        "required": [
          "vehicle",
          "violation_cost"
        ],
        "properties": {
          "vehicle": {
            "type": "string",
            "description": "Preferred vehicle id. An id that names no vehicle, or a vehicle listed\ntwice in one task's `preferences`, is rejected with HTTP 400.",
            "example": "v1"
          },
          "violation_cost": {
            "type": "number",
            "format": "double",
            "description": "Cost, in the objective's currency, incurred when a different vehicle\nserves the job. Must be finite and `>= 0`.",
            "example": 50.0,
            "maximum": 21474.83647,
            "minimum": 0
          }
        },
        "additionalProperties": false,
        "example": {
          "vehicle": "v1",
          "violation_cost": 50.0
        }
      },
      "VehicleSkill": {
        "type": "object",
        "description": "A capability a vehicle or shift provides, at a proficiency level:\n`{ \"name\": \"gas\", \"level\": 3 }`. Always an object; a bare string is\nrejected with HTTP 400.",
        "required": [
          "name"
        ],
        "properties": {
          "level": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "description": "Proficiency level, `>= 1`; absent = 1. Satisfies every job\nrequirement of this skill whose `min_level` is at most this value.",
            "example": 3,
            "minimum": 1
          },
          "name": {
            "type": "string",
            "description": "Skill name.",
            "example": "gas"
          }
        },
        "additionalProperties": false,
        "example": {
          "level": 3,
          "name": "gas"
        }
      },
      "Violation": {
        "type": "object",
        "description": "A single constraint violation detected while evaluating an imported solution.\n\nReported on stops (`routes[].stops[].violations`) and on routes\n(`routes[].violations`) in the `POST /v3/routing/evaluate` response.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ConstraintCode",
            "description": "The constraint broken. `max_stops`, `break`, `multi_trip`,\n`period_limit` and `quota` are route-level; `sequence` and `shipment`\nare on the stop; `unreachable`, `max_leg_travel` and `capacity` can be\neither. `unknown`\nmeans a stop was refused without a specific constraint being named\n(not expected in practice)."
          },
          "dimension": {
            "type": [
              "string",
              "null"
            ],
            "description": "The capacity dimension over its limit. Only on `capacity`,\n`unload_before_end`, `max_intake` and `load_compatibility`.",
            "example": "weight"
          },
          "excess": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "How far over the limit, in `unit`. On `capacity`, `time_window` (the\nseconds late), `shift_end`, `max_distance`, `max_route_duration`,\n`quota`, `unload_before_end`, `max_intake` and `load_compatibility`.",
            "example": 15
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of what was violated.",
            "example": "Cumulative load 30 exceeds vehicle capacity 15 (dimension weight)"
          },
          "unit": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/QuantityUnit",
                "description": "Unit of `excess`; present exactly when `excess` is."
              }
            ],
            "description": "Unit of `excess`; present exactly when `excess` is."
          }
        },
        "example": {
          "code": "capacity",
          "dimension": "weight",
          "excess": 15,
          "message": "Cumulative load 30 exceeds vehicle capacity 15 (dimension weight)",
          "unit": "load"
        }
      },
      "WarningCode": {
        "type": "string",
        "description": "The `code` of one `warnings[]` item.\n\nKnown values: `time_limit_raised`, `no_effect`. An open set: a later release may add values, so accept any string and handle the ones you know.",
        "x-extensible-enum": [
          "time_limit_raised",
          "no_effect"
        ]
      },
      "WorkloadShare": {
        "type": "object",
        "description": "Spreads work across vehicles: each vehicle's scheduled service time is\ncompared with its share of all the work, and the part outside a tolerance\nband is charged.\n\nThe balanced quantity is **service time only**: every served task's\n`service_duration_s`, scaled by the vehicle's `service_factor`. Travel,\n`setup_duration_s`, waiting and breaks are not counted, and a task-level\n`service_factors` entry scales the measure but not the target. Shares are\nfixed when the request is read: every task counts towards the total,\nserved or not, so with many unassigned tasks every vehicle sits under its\nshare and the term pulls work in without ordering the routes between them;\nbalancing pressure appears once routes enter their band. A vehicle with\nseveral shifts has its share split across them by the work each shift can\nreach (the service time of the tasks whose windows overlap it), weighted\nby shift length, so a day with no tasks carries none of the share; each\nshift is charged on its own part. An empty, non-exempt shift pays for its whole share, so pair the\nterm with `costs.per_route` or `per_used_vehicle` only when both are meant.\nSee `vehicles[].workload_weight` to give a part-time vehicle a smaller\nshare. Like `assignment_costs`, a request that sets the term is solved as\na whole rather than split into parts.",
        "required": [
          "per_imbalance_hour"
        ],
        "properties": {
          "per_imbalance_hour": {
            "type": "number",
            "format": "double",
            "description": "Money per hour a vehicle's service time is outside the band, in the\nrequest's currency. Greater than 0 and at least 0.036 (the internal\nresolution); omit `workload_share` to switch the term off.",
            "example": 35.0,
            "exclusiveMinimum": 0
          },
          "tolerance": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Half-width of the band as a fraction of the vehicle's share, `0` up to\nbut not including `1`. Default `0.1`: a vehicle within 10% of its share\nis not charged. The charge grows from the band edge.",
            "example": 0.1,
            "minimum": 0,
            "exclusiveMaximum": 1
          }
        },
        "additionalProperties": false
      },
      "GatewayError": {
        "type": "object",
        "description": "The gateway's own error answer on `/v3/routing/runs*`, not the `ErrorBody` shape. On `404` and `409` the `message` starts with a code (`not_found`, `run_not_finished`, `no_result`), a colon and a sentence; branch on the HTTP status and that code. The other answers carry no code.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "`GATEWAY_ERROR`, or the reason for a malformed `id`.",
            "example": "GATEWAY_ERROR"
          },
          "message": {
            "type": "string",
            "description": "Absent on a malformed `id`.",
            "example": "not_found: routing run d28568b1-34cc-4f89-b10b-dc24b26a8275"
          }
        }
      },
      "Run": {
        "description": "One async run. `status` selects the variant: which timestamps and `error` are present follows from it.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/RunQueued"
          },
          {
            "$ref": "#/components/schemas/RunRunning"
          },
          {
            "$ref": "#/components/schemas/RunSucceeded"
          },
          {
            "$ref": "#/components/schemas/RunFailed"
          },
          {
            "$ref": "#/components/schemas/RunCancelled"
          }
        ],
        "discriminator": {
          "propertyName": "status",
          "mapping": {
            "queued": "#/components/schemas/RunQueued",
            "running": "#/components/schemas/RunRunning",
            "succeeded": "#/components/schemas/RunSucceeded",
            "failed": "#/components/schemas/RunFailed",
            "cancelled": "#/components/schemas/RunCancelled"
          }
        }
      },
      "RunCancelled": {
        "type": "object",
        "description": "A run cancelled before it finished. `started_at` is absent when it was cancelled while `queued`; it never returns a plan.",
        "required": [
          "id",
          "status",
          "links",
          "finished_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The run id. Use it in the paths of the other endpoints.",
            "example": "d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "status": {
            "type": "string",
            "enum": [
              "cancelled"
            ],
            "description": "`cancelled`."
          },
          "links": {
            "$ref": "#/components/schemas/RunLinks"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When a worker claimed the run, in UTC. Absent while the run is `queued`.",
            "example": "2026-10-15T07:40:59Z"
          },
          "finished_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run reached a final state, in UTC. Absent before then.",
            "example": "2026-10-15T07:41:00Z"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.",
            "example": "2027-10-15T07:41:00Z"
          }
        }
      },
      "RunError": {
        "type": "object",
        "description": "Why a run `failed`, in the `ErrorBody` shape.",
        "required": [
          "status",
          "code",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "description": "The HTTP status as text.",
            "example": "INTERNAL_SERVER_ERROR"
          },
          "code": {
            "type": "string",
            "description": "One code per cause: `invalid_request` (the request failed a check only the worker makes, such as a locked stop that cannot be driven; see `errors[]`), `travel_provider_error` (travel times could not be fetched), `internal` (a fault on the worker side, or a run that never started within 30 minutes), `worker_lost` (the worker stopped before it finished, or the run exceeded 6,000 s).",
            "example": "worker_lost"
          },
          "message": {
            "type": "string",
            "description": "Human-readable summary.",
            "example": "the worker stopped before finishing"
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `X-Request-Id` of the request that submitted the run."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RequestIssue"
            },
            "description": "One entry per problem found in the request, as in `ErrorBody`."
          }
        }
      },
      "RunFailed": {
        "type": "object",
        "description": "A run that stopped with an error. `started_at` is absent when the run never started.",
        "required": [
          "id",
          "status",
          "links",
          "error",
          "finished_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The run id. Use it in the paths of the other endpoints.",
            "example": "d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "status": {
            "type": "string",
            "enum": [
              "failed"
            ],
            "description": "`failed`."
          },
          "links": {
            "$ref": "#/components/schemas/RunLinks"
          },
          "error": {
            "$ref": "#/components/schemas/RunError",
            "description": "Present when `status` is `failed`."
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When a worker claimed the run, in UTC. Absent while the run is `queued`.",
            "example": "2026-10-15T07:40:59Z"
          },
          "finished_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run reached a final state, in UTC. Absent before then.",
            "example": "2026-10-15T07:41:00Z"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.",
            "example": "2027-10-15T07:41:00Z"
          }
        }
      },
      "RunLinks": {
        "type": "object",
        "description": "Paths of the run, relative to the API host.",
        "required": [
          "self",
          "result"
        ],
        "properties": {
          "self": {
            "type": "string",
            "description": "`GET` it to poll the run.",
            "example": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "result": {
            "type": "string",
            "description": "`GET` it for the plan once the run `succeeded`.",
            "example": "/v3/routing/runs/d28568b1-34cc-4f89-b10b-dc24b26a8275/result"
          }
        }
      },
      "RunOptions": {
        "type": "object",
        "description": "Solve options.",
        "properties": {
          "polyline": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/PolylineDetail",
                "description": "Return road geometry for each route as `routes[].polyline`:\n`simplified` or `full`. Omitted → no geometry (the default). One value\nfor the whole request, named like the response field it fills."
              }
            ],
            "description": "Return road geometry for each route as `routes[].polyline`:\n`simplified` or `full`. Omitted → no geometry (the default). One value\nfor the whole request, named like the response field it fills."
          },
          "seed": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Random seed for the search: `0` to `9007199254740991` (2^53 − 1, the\nlargest integer JavaScript holds exactly), HTTP 400 above.\n**Default.** `42`: omitting it is the same as sending `42`, so send\ndifferent values to explore different plans. Repeated runs on one\nmachine usually return an identical plan; a materially faster or slower\nmachine can differ.",
            "default": 42,
            "example": 42,
            "maximum": 9007199254740991,
            "minimum": 0
          },
          "time_limit_s": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Upper bound on the search time in seconds, fractions allowed, building\nthe first plan included: on a large request that plan is completed\nwith a cheaper insertion once it has used half the budget (not when\nthe request has shipments: then the first plan is always built in\nfull).\n**Default.** 60 s plus 20 ms per task (jobs and shipments combined), so 100 tasks search up to 62 s. Maximum 3600: a larger value is rejected with HTTP 400. A value below 0.1 is raised to a 100 ms floor.\n**Pitfall.** Fetching travel times and waiting for capacity are not\ndeducted from it, so the request takes longer than\nthis value. A longer search can lower `score.cost` even when every\ntask is assigned; an unassigned task with `category: \"time_limit\"` is\nthe sign that more time would also place it.",
            "example": 2.5,
            "maximum": 3600,
            "minimum": 0
          },
          "travel_fallback": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TravelFallback",
                "description": "What to do when travel times cannot be fetched from Solvice Maps.\n**Default.** `estimate`: solves on estimated travel and sets\n`summary.travel_estimated`; `fail` returns the 502/503 instead.\nLocations that Maps rejects for spanning more than one region are a 400.\nNo effect with `travel.engine: \"straight_line\"`, which fetches nothing."
              }
            ],
            "description": "What to do when travel times cannot be fetched from Solvice Maps.\n**Default.** `estimate`: solves on estimated travel and sets\n`summary.travel_estimated`; `fail` returns the 502/503 instead.\nLocations that Maps rejects for spanning more than one region are a 400.\nNo effect with `travel.engine: \"straight_line\"`, which fetches nothing.",
            "default": "estimate"
          }
        },
        "additionalProperties": false,
        "example": {
          "polyline": "full",
          "seed": 42,
          "time_limit_s": 5
        }
      },
      "RunQueued": {
        "type": "object",
        "description": "A run no worker has claimed yet. No timestamps.",
        "required": [
          "id",
          "status",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The run id. Use it in the paths of the other endpoints.",
            "example": "d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued"
            ],
            "description": "`queued`."
          },
          "links": {
            "$ref": "#/components/schemas/RunLinks"
          }
        }
      },
      "RunRequest": {
        "type": "object",
        "description": "Request body for `POST /v3/routing/runs`: the `POST /v3/routing/solve` body, with a longer `options.time_limit_s`.",
        "required": [
          "problem"
        ],
        "properties": {
          "options": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/RunOptions",
                "description": "Solve options."
              }
            ],
            "description": "Solve options."
          },
          "plan": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Plan",
                "description": "Warm start: the plan the search starts from instead of constructing\nfrom scratch (re-optimization). A result's `plan` goes in as it stands.\nSee `plan.routes[].locked_count` for freezing a dispatched prefix.\n\nA **hint, not a guarantee**: an unlocked stop that violates a hard\nconstraint (e.g. capacity, skills, eligibility, `limits.*`, or a time\nwindow with no `per_late_hour` set) is left unassigned and the\nsearch reinserts it wherever it legitimately fits, or it surfaces in\n`unassigned[]` with a typed reason. On synchronous solve and stream, an\ninfeasible locked stop is a 400. `POST /v3/routing/runs` checks the\nproblem at submission, not the plan, so there the run ends `failed`\nwith `BAD_REQUEST` instead. A pinned stop outside a `locked_count`\nprefix (a shipment leg whose other leg is inside counts as inside) is\nnever a 400 or a failed run: one that cannot be served is in\n`unassigned[]` (see `pinned`)."
              }
            ],
            "description": "Warm start: the plan the search starts from instead of constructing\nfrom scratch (re-optimization). A result's `plan` goes in as it stands.\nSee `plan.routes[].locked_count` for freezing a dispatched prefix.\n\nA **hint, not a guarantee**: an unlocked stop that violates a hard\nconstraint (e.g. capacity, skills, eligibility, `limits.*`, or a time\nwindow with no `per_late_hour` set) is left unassigned and the\nsearch reinserts it wherever it legitimately fits, or it surfaces in\n`unassigned[]` with a typed reason. On synchronous solve and stream, an\ninfeasible locked stop is a 400. `POST /v3/routing/runs` checks the\nproblem at submission, not the plan, so there the run ends `failed`\nwith `BAD_REQUEST` instead. A pinned stop outside a `locked_count`\nprefix (a shipment leg whose other leg is inside counts as inside) is\nnever a 400 or a failed run: one that cannot be served is in\n`unassigned[]` (see `pinned`)."
          },
          "problem": {
            "$ref": "#/components/schemas/Problem",
            "description": "The problem: tasks, fleet, depots, relations, objective, travel."
          }
        },
        "additionalProperties": false,
        "example": {
          "options": {
            "seed": 42,
            "time_limit_s": 5
          },
          "problem": {
            "depots": [
              {
                "id": "gent",
                "location": [
                  3.7174,
                  51.0543
                ]
              }
            ],
            "jobs": [
              {
                "id": "job-1",
                "location": [
                  3.725,
                  51.05
                ],
                "pickup_load": {
                  "weight": 20
                },
                "required_skills": [
                  {
                    "name": "fridge"
                  }
                ],
                "service_duration_s": 300,
                "time_windows": [
                  {
                    "from": "2026-07-01T09:00:00+02:00",
                    "to": "2026-07-01T12:00:00+02:00"
                  }
                ]
              },
              {
                "id": "job-2",
                "location": [
                  3.71,
                  51.06
                ],
                "pickup_load": {
                  "weight": 35
                },
                "service_duration_s": 600
              }
            ],
            "objective": {
              "costs": {
                "per_route_hour": 35.0,
                "per_travel_km": 0.2
              },
              "currency": "EUR"
            },
            "vehicles": [
              {
                "capacity": {
                  "weight": 500
                },
                "id": "v1",
                "profile": "car",
                "shifts": [
                  {
                    "end": {
                      "depot": "gent"
                    },
                    "from": "2026-07-01T08:00:00+02:00",
                    "id": "mon",
                    "start": {
                      "depot": "gent"
                    },
                    "to": "2026-07-01T17:00:00+02:00"
                  }
                ],
                "skills": [
                  {
                    "name": "fridge"
                  }
                ]
              }
            ]
          }
        }
      },
      "RunRunning": {
        "type": "object",
        "description": "A run a worker has claimed.",
        "required": [
          "id",
          "status",
          "links",
          "started_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The run id. Use it in the paths of the other endpoints.",
            "example": "d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "status": {
            "type": "string",
            "enum": [
              "running"
            ],
            "description": "`running`."
          },
          "links": {
            "$ref": "#/components/schemas/RunLinks"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When a worker claimed the run, in UTC. Absent while the run is `queued`.",
            "example": "2026-10-15T07:40:59Z"
          }
        }
      },
      "RunSucceeded": {
        "type": "object",
        "description": "A run that finished. Read the plan with `GET /v3/routing/runs/{id}/result`.",
        "required": [
          "id",
          "status",
          "links",
          "started_at",
          "finished_at",
          "expires_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The run id. Use it in the paths of the other endpoints.",
            "example": "d28568b1-34cc-4f89-b10b-dc24b26a8275"
          },
          "status": {
            "type": "string",
            "enum": [
              "succeeded"
            ],
            "description": "`succeeded`."
          },
          "links": {
            "$ref": "#/components/schemas/RunLinks"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "description": "When a worker claimed the run, in UTC. Absent while the run is `queued`.",
            "example": "2026-10-15T07:40:59Z"
          },
          "finished_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run reached a final state, in UTC. Absent before then.",
            "example": "2026-10-15T07:41:00Z"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the run and its plan are deleted: `finished_at` plus 365 days. Absent before the run is final.",
            "example": "2027-10-15T07:41:00Z"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  }
}
