Skip to main content
POST
Suggest best insertions for new jobs

Authorizations

Authorization
string
header
required

Body

application/json

Request body for POST /v3/routing/suggest.

Given existing routes over the jobs/vehicles problem, ranks the best feasible insertion positions for each entry in new_jobs.

vehicles
object[]
required

Available vehicles.

new_jobs
object[]
required

New visits to rank insertions for. At least one is required.

routes
object[]
required

Current route assignments — the jobs already placed (not moved).

initial_routes
object[] | null

Warm-start: route assignments the search starts from instead of constructing from scratch (re-optimization). Unknown vehicle/job ids are rejected with HTTP 400. See [RouteAssignment::locked_count] for freezing a dispatched prefix. Accepted for solve-payload compatibility on /v3/routing/evaluate and /v3/routing/suggest and ignored there — routes is the input on those endpoints.

jobs
object[]

Single-stop visits to serve.

objective
null | object

Objective configuration.

Example:
options
null | object

Solver runtime options.

Example:
relations
(Ordered · object | Same resource · object | Same day · object | Synchronized · object)[] | null

Ordering, grouping, and synchronization constraints.

A hard constraint between tasks. Tagged union; each variant carries only its valid fields.

All four variants are wired: ordered (via job_ids or groups), same_resource, same_day, and synchronized. Member selection is either explicit job_ids or a group tag (same_resource/ same_day; validated not-both) — ordered uses job_ids or the cross-group groups list.

(The never-wired consecutive and same_route variants, the per-relation id and soft violation_cost fields, ordered's group/min_interval_s/ max_interval_s/measure_from, and synchronized.tasks[*].vehicles were removed: every one was rejected with HTTP 400 on any value. Each can return as a new field/variant once its core primitive exists — relations are hard-only until then.)

Example:
shipments
object[]

Bound pickup→delivery shipments to serve.

max_suggestions
integer | null

Max ranked options per new job (clamped to 1..=10, default 5).

Required range: x >= 0
Example:

5

Response

Suggestions computed

Response body for POST /v3/routing/suggest.

elapsed_ms
integer<int64>
required

Wall-clock time taken by the request, in milliseconds.

Required range: x >= 0
Example:

8

suggestions
object[]
required

One entry per new job, in new_jobs order.