Skip to main content
PUT
Error

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
agencyId
string
required

The agency id.

Pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$
Example:

"LND_Agency-42"

​
planId
string
required

The plan id. At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$

Query Parameters

​
force
boolean
default:false

If true, on an archived item, the requested action will be forced and the item will be unarchived.

Body

application/json

The Plan to update.

A plan for a date and agency, with resource and orders associated.

​
resources
object[]
required

The list of resources (vehicle/driver pairs) available to fulfill the plan's orders.

​
status
object

The plan's processing status across the optimization pipeline (waiting room, creation, optimization, and traffic-waiting stages), each tracking which plan version is currently waiting and currently running. Poll this field to know when a new solution is ready instead of relying on a push/webhook mechanism. See PlanStatus for the full breakdown of each stage.

​
state
enum<string>

The corresponding plan's state.

  • waiting: The plan was received and is awaiting processing.
  • processing: The plan is being processed.
  • preOptimizing: The plan is being optimized while awaiting traffic or other information.
  • preOptimized: While still awaiting traffic or other information, one of the following events has occurred: no better solution can be produced, or the optimization period has reached its limit. Note that 'preOptimized' should be followed by 'optimizing' and 'optimized'.
  • optimizing: The plan is being optimized with all required information.
  • optimized: This state can be triggered by one of the following events: no better solution can be produced, or the optimization period has reached its limit.
  • stopped: The plan's awaiting optimizations were canceled.
  • deleted: The plan was deleted and awaiting optimizations were canceled.
  • interrupted: The plan was either updated, stopped or deleted during its optimization.
Available options:
waiting,
processing,
preOptimizing,
preOptimized,
optimizing,
optimized,
stopped,
deleted,
interrupted
​
properties
object

Free-form key-value pairs (strings only) with no impact on optimization. Used to carry integration-specific information (for example an internal reference) that is returned unchanged in the plan and its solution. Can also be set on resources, orders, and stops.

​
orders
object[]

The list of orders (sequences of stops) to be planned across the available resources.

​
additionalOperationDurations
object[]

Additional operation time for a resource and a stop, according to tags (pairs of tags must be unique).

​
operationDurationPoliciesByResourceTag
object

Policies to remove the operation durations, by resource tag.

​
forbiddenAssignments
object[]
deprecated
​
incompatibleStopTags
string[][]
deprecated

Incompatibilities between stop tags (all elements must be different regardless of order).

A pair of incompatible stop tags.

Required array length: 2 elements

Stop tag.

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$
Example:
Example:
​
additionalConstraints
object[]

A list of advanced constraints that go beyond what the standard modeling objects (resources, orders, stops) can express, each identified by a type (for example atLeastOneValidCapacity, forbiddenAssignment, incompatibleStopTags, atLeastOneConstraint, capacities, maxStopTagGroups, or removalStrategy). See the constraints catalog for the full list and their parameters.

If the tour has not, at each stop, one of its capacities lower than or equal to the link limit, then the tour is invalid.

​
globalConstraints
object[]

List of global constraints to be satisfied by the returned solution.

​
accessDurationsByStopTag
object

Access durations is an additional duration before the beginning of a group of stops with the same stop tag.

Example:
​
overlappingCapacitiesByStopTag
object

This field allows users to define a limit in the number of resources that are simultaneously present at stops sharing the same stop tag.

Example:
​
setupDurations
object[]

Defines an additional duration incurred when a resource transitions from a stop tagged fromStopTag to a stop tagged toStopTag (for example customs crossings between countries, or cleaning required between incompatible cargo types), identified by the "setup:" tag convention.

​
objectives
enum<string> · object · object[]

The ordered list of optimization objectives, processed lexicographically: the algorithm prioritizes improving higher-ranked objectives before lower-ranked ones, so the order should reflect business priorities. Defaults to a sequence that works well for most cases. See ObjectivesEnum for the available objectives.

The available optimization objectives, processed lexicographically in the order provided in Plan.objectives:

  • maximizeMandatoryStops: Maximizes the number of mandatory stops ("optional": false) planned. Should generally be first in the list to ensure at least some planning.
  • minimizeResources: Minimizes the number of resources used without violating constraints or degrading higher-priority objectives. Should not be first, as the optimal solution might otherwise be to use no resources.
  • minimizeWorkingDuration: Minimizes the total working time of the routes, including travel, service, breaks, and waiting times.
  • minimizeDistance: Minimizes the total distance traveled by all routes.
  • minimizeDelay: Minimizes the total delay across all planned stops, calculated as the difference between the planned time and the end of the preferred time window.
  • minimizeCosts: Minimizes the total cost of resources, considering factors like distance, working time, and the number of planned orders. See the Cost schema for the available cost components.
  • maximizeOptionalStops: Maximizes the number of optional orders ("optional": true) planned, without violating constraints or degrading higher-priority objectives. Typically placed after minimizeResources.
  • maximizePreferredStops: Maximizes the assignment of preferred stops to resources based on matching preferredStopTags / tags.
  • minimizeOverOverlappingCapacitiesOnStops: Minimizes the number of vehicles present simultaneously at stops with overlapping capacities (e.g. limited cross-docking capacity). May cause optimization delays; use only if necessary.
  • minimizeLargestTourDuration and minimizeEarlyLoadings: additional objectives; see Kardinal support for details on these two.
Available options:
maximizeMandatoryStops,
minimizeDelay,
minimizeCosts,
minimizeResources,
minimizeOverOverlappingCapacitiesOnStops,
maximizeOptionalStops,
maximizePreferredStops,
minimizeLargestTourDuration,
minimizeWorkingDuration,
minimizeDistance,
minimizeEarlyLoadings
​
maxOptimizationDuration
string

A period of time, expressed in the ISO8601 duration format.

Pattern: ^P(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(\d+H)?(\d+M)?(\d+S)?)?$
Example:

"PT4M"

​
tz
string

The time zone is a string code which identifies a region of the world in the "time zone database", also called "tz database". The tz database is a partition of the world into regions where local clocks all show the same time. This database gives the rules for time offset and daylight saving time in each region.

How do we use it?

In order to work with time events accurately, we usually use datetimes in the iso-8601 format, without explicit time zone. This format is quite well suported by many programming languages, and it is well suited for technical data exchange. But it is not easy to use for humans.

For instance, here are three datetimes in iso-8601 format, which give the same exact moment in time:

  • "2025-05-22T05:43:00Z"
  • "2025-05-22T06:43:00+01:00"
  • "2025-05-22T07:43:00+02:00"

For a non-technical user, it is difficult to know how to relate this to the time displayed on a watch or a clock.

We improve the user experience by adding the support of local datetimes, thanks to the use of the time zone, which allows to transform a local datetime into an iso-8601 datetime:

  • local datetime + timezone (tz) = iso-8601 datetime

For instance, here are five datetimes which all give the same exact moment in time:

  • "2025-05-22T05:43:00Z"
  • "2025-05-22T06:43:00+01:00"
  • "2025-05-22T07:43:00+02:00"
  • "2025-05-22 07:43:00" + timezone "tz": "Europe/Paris"
  • "2025-05-22 07:43" + timezone "tz": "Europe/Paris"

Note: the last example ("2025-05-22 07:43") illustrates the support of local datetimes without seconds, which can be very practical for users.

In order for local datetimes to be supported, some JSON input objects contain a "tz" time zone property. This "tz" property is used to pre-process the JSON input payload, like this:

  • We check if a valid timezone can be extracted from the "tz" property,
  • If so, we perform the following actions:
    • Walk through the whole JSON content to look for local datetimes,
    • Use the timezone to transform each local datetime into an iso-8601 datetime.

Important: some objects contain a "properties" sub-object, which is a map of custom client data; the content of the "properties" sub-objects is always excluded from the time zone pre-processing.

Example:

"Europe/Paris"

​
lateDeparture
boolean
default:false

True if lateDeparture is requested for Resources, false otherwise.

​
sharedCapacities
boolean
default:false

True if sharedCapacities is requested for Resources, false otherwise. It enables resources to share capacities between stops of different orders.

​
emptyThresholdByCapacityByResourceTag
object

Thresholds for capacities below which a resource is considered "empty" for empty distance calculation, grouped by resource tag. A resource is "empty" (kilometers traveled count as empty distance) when all capacities are at or below their threshold. The wildcard tag "*" matches all resources.

Example:
​
avoidEarlyLoadingsByResourceTag
object

Early loading declarations grouped by resource tag. The wildcard tag "*" matches all resources. Each entry identifies a stop tag and optional capacities used to compute the minimizeEarlyLoadings objective.

Example:
​
CO2EmissionCalculationByResourceTag
object

Optional CO2 emission calculation parameters grouped by resource tag. Each value is a Cost-shaped object. Applies to every resource carrying the corresponding tag. When set, the resulting emissions are reported on tours as CO2Emission and aggregated on the solution as CO2Emission. If a resource matches multiple tags, only its first declared matching tag is used. Overridden by the resource-level declaration.

Example:

Response

Plan response updated.

[TO_VALIDATE] Description pending review by a Kardinal engineer.

​
item
object

A plan for a date and agency, with resource and orders associated.

​
agencyId
string

The agency id.

Pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$
Example:

"LND_Agency-42"

​
planId
string

The plan id.

Pattern: ^[a-zA-Z0-9-._~:@!$,]+$
Example:

"plan-AB"

​
planVersion
integer
read-only

The plan version.

Required range: x >= 1
Example:

42