canonical: https://jentic.com/apis/logisticsosapi.com/logisticsos

# LogisticsOS API Services

Jentic publishes the only available OpenAPI specification for LogisticsOS API Services, keeping it validated and agent-ready. LogisticsOS is a route optimisation engine that exposes asynchronous Vehicle Routing Problem (VRP) and Traveling Salesman Problem (TSP) solvers, on-demand and replan operations for live fleet adjustments, and direct map-matching, matrix routing, and routing endpoints. Each long-running solver follows a POST-then-poll pattern: submit the problem, then GET the result by job id.

## For AI agents

Solve vehicle routing and TSP problems, replan live routes, match GPS traces to roads, and calculate route matrices for fleet operations.

## Scope

Does not handle driver dispatch UIs, telematics device management, or proof-of-delivery capture - use for route optimisation, replanning, matrix routing, and map matching only.

## Capabilities

- Submit a Vehicle Routing Problem with vehicles, depots, and stops via POST `/vrp/v3` and retrieve the optimised plan asynchronously
- Solve a Traveling Salesman Problem for a single vehicle with POST `/tsp/v3`
- Replan an in-progress route after disruptions through POST `/replan/v3`
- Add live on-demand stops to a running plan via POST `/ondemand/v3`
- Calculate routes between pairs of coordinates with POST `/route/v1`
- Compute travel-time and distance matrices via POST `/matrix/v1`
- Snap raw GPS traces to the road network through POST `/match/v1`

## Use cases

### Daily Delivery Route Optimisation

Generate the optimal delivery plan each morning by POSTing a Vehicle Routing Problem with the day's stops, vehicle constraints, and time windows to `/vrp/v3.` The solver returns a job id; poll GET `/vrp/v3` with that id to retrieve sequenced routes per vehicle. This typically replaces manual dispatcher work for fleets above ~20 vehicles.

Example prompt: POST `/vrp/v3` with the vehicles array and stops array, then GET `/vrp/v3`?id=<jobId> until status='complete'.

### Live Replanning after Disruption

When a vehicle breaks down or a stop is cancelled, recompute the remaining plan with POST `/replan/v3` using the current vehicle positions and the updated stop list. The replan engine reuses progress already made instead of solving from scratch, keeping ETAs accurate.

Example prompt: POST `/replan/v3` with currentPositions and remainingStops, then poll GET `/replan/v3`?id=<jobId>.

### Travel-Time Matrix for Distance Calculations

Build a pairwise travel-time matrix for a set of locations via POST `/matrix/v1.` The matrix powers downstream optimisation, ETA prediction, and what-if analysis without paying the full cost of solving a VRP each time.

Example prompt: POST `/matrix/v1` with coordinates=[[lon1,lat1],[lon2,lat2],...] then GET `/matrix/v1`?id=<jobId>.

### GPS Trace Map Matching

Snap noisy GPS traces from telematics devices to the actual road network using POST `/match/v1.` The cleaned trace produces accurate distance and street-name reporting and feeds proof-of-delivery and audit workflows.

Example prompt: POST `/match/v1` with the raw trace coordinates and radius parameter to receive the matched route geometry.

### AI Agent Route Planning via Jentic

An AI dispatcher agent can submit a VRP, poll the result, and dispatch the assigned routes to drivers without managing API keys. Jentic exposes the LogisticsOS solver and result endpoints as MCP tools so the agent invokes them by intent.

Example prompt: Through Jentic, search 'optimise vehicle routes', load the LogisticsOS POST `/vrp/v3` operation, execute it, then load GET `/vrp/v3` to fetch the result.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/vrp/v3` | Submit a Vehicle Routing Problem |
| GET | `/vrp/v3` | Retrieve VRP result by job id |
| POST | `/tsp/v3` | Submit a Traveling Salesman Problem |
| POST | `/replan/v3` | Replan an in-progress route |
| POST | `/ondemand/v3` | Add stops to a live plan |
| POST | `/route/v1` | Calculate a route between coordinates |
| POST | `/matrix/v1` | Compute a travel-time matrix |
| POST | `/match/v1` | Snap a GPS trace to the road network |

## Key resources

- **VRP** — Submit and retrieve Vehicle Routing Problem jobs
- **TSP** — Submit and retrieve Traveling Salesman Problem jobs
- **On-demand** — Add live stops to an active plan
- **Replan** — Recompute routes after disruptions
- **Route** — Calculate routes between coordinates
- **Matrix** — Compute travel-time and distance matrices
- **Match** — Snap GPS traces to the road network

## Why Jentic

- **Setup:** Wiring the LogisticsOS API by hand means setting up its API key, attaching it to each solver call, and building the routing, matrix, and replanning request payloads yourself. Through Jentic you install once, import LogisticsOS from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** LogisticsOS solver endpoints take their whole problem in the request body with no account resource in the URL path, so scoping is by operation: limit the agent to the operations it needs, such as vehicle routing or matrix computation, and leave out on-demand or map matching if the agent does not use them.
- **Credential handling:** Your LogisticsOS API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'optimise delivery routes' or 'compute a distance matrix', and Jentic returns the matching LogisticsOS operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Routific API** — Vehicle routing solver with a simpler one-shot synchronous API
- **GraphHopper Directions API** — Routing engine with both directions and route optimisation tiers
- **Route4Me API** — Last-mile route planner with mobile driver apps included
- **HERE Maps API** — Source of truth for live traffic and truck routing rules

## FAQ

### Why is there no official OpenAPI spec for LogisticsOS API Services?

LogisticsOS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call LogisticsOS API Services via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the LogisticsOS API use?

LogisticsOS uses an API key passed in the request (ApiKeyAuth scheme). Through Jentic the key is held in the encrypted vault and injected at execution, so the raw key never appears in the agent's context.

### How does the asynchronous VRP solver work?

Submit the problem with POST `/vrp/v3` and the API returns a job id immediately. Poll GET `/vrp/v3` with that id until status reports completion, then read the optimised routes from the response. The same pattern applies to `/tsp/v3`, `/ondemand/v3`, `/replan/v3`, and `/matrix/v1.`

### Can I replan a route after a vehicle breaks down?

Yes. POST `/replan/v3` with the current vehicle positions and the remaining stops, then poll GET `/replan/v3` for the updated plan. The replanner reuses completed work instead of solving from scratch.

### How do I optimise delivery routes through Jentic?

Run `pip install jentic`, search Jentic for 'optimise vehicle routes', load the LogisticsOS POST `/vrp/v3` operation, and execute it with the vehicles and stops payload. Then load GET `/vrp/v3` to fetch the result by job id.

### What are the rate limits for the LogisticsOS API?

The spec does not embed numeric rate limits. Solver-style endpoints are job-throttled rather than request-throttled, so concurrent jobs are the relevant cap. Implement backoff on HTTP 429.

### Can I limit what my agent is allowed to do with the LogisticsOS API?

Yes. Because you run Jentic One yourself, your own rules decide which LogisticsOS operations and credentials the agent may use. Since every solver call carries its whole problem in the request body with no account resource in the URL, scoping is by operation: you can allow only the endpoints the agent needs, such as POST `/vrp/v3` for vehicle routing or POST `/matrix/v1` for travel-time matrices. Operations the agent does not need, like POST `/ondemand/v3` for live stops or POST `/match/v1` for GPS map matching, can be left out so it never calls them.