OpenAPI specification - Solvice Docs

V3 is in beta. General availability (GA) is planned for January 2027.

One OpenAPI 3.1 file describes every V3 Routing API endpoint: solve, evaluate and suggest, their three validate counterparts, and the four async-run endpoints. Use it to generate a client, to check requests in your tests, or to import the API into an HTTP tool.

solvice-routing-v3.openapi.json

OpenAPI 3.1, JSON, about 290 KB

curl -O https://docs.solvice.io/api-reference/solvice-routing-v3.openapi.json

What the file contains

All ten endpoints, tagged Routing (/v3/routing/solve, /evaluate, /suggest and /validate/solve, /validate/evaluate, /validate/suggest) and Runs (/v3/routing/runs and its status, result and cancel paths). See Introduction for what each one does.
The server and authentication: https://api.solvice.io, with your API key in the Authorization header as the bare key, no Bearer prefix.
Every request and response schema, with the field descriptions from this reference and the limits the API enforces, such as minimum, maximum and maxItems.

It is the same contract as the endpoint pages in this reference. Field names, schema names and the JSON on the wire are identical. The file changes with every API release, and during the beta a release can rename or remove fields. Download it again when you update your integration.

Generate a client

For TypeScript, use the @solvice/routing package (beta), which is typed from this contract. For other languages, generate a client from the file. OpenAPI 3.1 support differs between generators. openapi-python-client generates a working Python client from this file. The python generator of openapi-generator 7.14 does not yet handle its nullable fields.

Generate the package

uvx openapi-python-client generate --path solvice-routing-v3.openapi.json --output-path solvice_routing --meta none

Without uv, run pip install openapi-python-client and then the same command without uvx. --meta none writes the package alone; it needs httpx, attrs and python-dateutil installed.

Call the API

The generated client sends Authorization: Bearer <token> unless you set prefix="". Set it, because the API expects the bare key.

import os

from solvice_routing import AuthenticatedClient
from solvice_routing.api.routing import solve
from solvice_routing.models import ErrorBody, SolveRequest

client = AuthenticatedClient(
    base_url="https://api.solvice.io",
    token=os.environ["SOLVICE_API_KEY"],
    prefix="",
    timeout=30,
)

request = SolveRequest.from_dict({
    "problem": {
        "jobs": [{"id": "delivery-1", "location": [4.7005, 50.8798], "service_duration_s": 300}],
        "vehicles": [{"id": "truck-1", "shifts": [{
            "id": "mon",
            "from": "2026-04-01T08:00:00+02:00",
            "to": "2026-04-01T17:00:00+02:00",
            "start": {"location": [4.3517, 50.8503]},
            "end": {"location": [4.3517, 50.8503]},
        }]}],
    },
    "options": {"time_limit_s": 1},
})

result = solve.sync(client=client, body=request)
if isinstance(result, ErrorBody):
    print(result.code, [item.code for item in result.errors])
else:
    print(result.summary.tasks.served, "served, cost", result.summary.score.cost)

solve.sync returns a SolveResponse, or an ErrorBody for a 400, 403, 413, 415, 500, 502 or 503. To check a request without solving it, call validate_solve instead, which returns a ValidateResponse.

Whichever generator you use:

Accept unknown values. Responses can gain fields, and every code or type in a response can gain values, without a new major version. Configure the generator to accept them; for openapi-generator, set enumUnknownDefaultCase=true.
Send only documented fields. Requests are strict: an unknown field is a 400 with an unknown_field item.
Do not parse message. Branch on the HTTP status, then on code and errors[].code. See Errors.
Authentication and rate-limit errors (401, 429) come from the API gateway in its own shape, not as an ErrorBody.

solvice-routing-v3.openapi.json

​What the file contains

​Generate a client

What the file contains

Generate a client