Skip to main content
POST
Create a plan

Authorizations

​
Authorization
string
header
required

JWT bearer token, sent as Authorization: Bearer <token>. Two kinds of token are accepted:

  • A session token (1 hour), obtained through the interactive Console login flow. Used to sign in to the Console; not meant to be used against this API.
  • A long-term API token (366 days), obtained once via the Console and meant to be stored by your integration. It is the credential recommended for backend use, since it does not depend on repeating the interactive login flow.

Body

application/json

The plan to create.

A full plan for a date and agency, with its associated resources, orders, constraints, and so on.

​
resources
object[]
required

Resources (vehicles, drivers, or vehicle-and-driver pairs) available to serve this plan's orders.

Default. Capped at 250 entries per plan — see Limits and quotas.

​
properties
object

Free-form metadata map (string to string), with no effect on optimization. Returned unchanged on the object and in the solution. Typical uses: a driver's name, a vehicle's plate, a customer name or address, a client reference.

Example:
​
orders
object[]

Orders (individual stops or groups of stops) to be served by this plan.

Default. Capped at 3,000 entries per plan — see Limits and quotas.

​
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.

Example:
​
additionalConstraints
object[]

Extra constraints layered on top of resources' and orders' own fields, such as forbidden assignments or capacity ceilings shared across a group of stops.

additionalConstraints scope. At every stop of the tour, at least one of the listed capacities must be at or below its given threshold — an OR across the listed capacities, checked at each stop, not a requirement that they all hold together.

When to use. For sequencing stop types or validating multi-compartment configurations. If the tour has not, at each stop, one of its capacities lower than or equal to the given limit, the tour is invalid.

​
globalConstraints
object[]

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

​
accessDurationsByStopTag
object

Fixed extra duration charged once, before the first of a group of consecutive stops sharing a tag, in ISO 8601 duration format.

When to use. For a cost paid once per visit to a tagged location, such as a 30-minute dock access time. For a cost paid on every stop regardless of what came before it, use a stop's own operationDuration instead.

Example:
​
overlappingCapacitiesByStopTag
object

Target maximum number of resources physically present at the same time at stops sharing a tag.

When to use. To model a shared bottleneck resource such as a depot with a limited number of loading docks, or a cross-dock with limited simultaneous capacity, for example limiting a two-dock depot to 2 resources at once.

Modelling pitfall. A soft limit, not a hard cap: overruns are minimized by the minimizeOverOverlappingCapacitiesOnStops objective, so how firmly the engine keeps to the limit depends on that objective's position in objectives, and it has no effect if that objective is left out.

Example:
​
setupDurations
object[]

Sequence-dependent changeover times to add whenever a resource travels directly between two stops carrying a matching pair of tags.

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

Objectives the engine optimizes for this plan; see PlanObjectives for how priority order drives trade-offs.

Name of a built-in objective, used as an entry in PlanObjectives.

  • maximizeMandatoryStops: Maximizes the number of non-optional stops actually planned.
  • minimizeDelay: Minimizes the sum of delays against stops' preferredTimeWindows; only lateness counts, never earliness.
  • minimizeCosts: Minimizes the plan's total cost, as defined by each resource's cost.
  • minimizeResources: Favours using fewer resources over spreading stops across more of them.
  • minimizeOverOverlappingCapacitiesOnStops: Minimizes how far the limits set in Plan.overlappingCapacitiesByStopTag are exceeded, in resources simultaneously present beyond the limit.
  • maximizeOptionalStops: Maximizes the number of optional stops planned in addition to mandatory ones.
  • maximizePreferredStops: Maximizes stops matched to a resource's preferredStopTags.
  • minimizeLargestTourDuration: Minimizes the working duration of the single longest tour across the fleet (travel, service, and waiting time), balancing workload between resources.
  • minimizeWorkingDuration: Minimizes the total working duration summed across every tour, waiting time included.
  • minimizeDistance: Minimizes the total distance travelled summed across every tour.
  • minimizeEarlyLoadings: Minimizes early loadings; pairs with a resource's avoidEarlyLoadings declarations.
Available options:
maximizeMandatoryStops,
minimizeDelay,
minimizeCosts,
minimizeResources,
minimizeOverOverlappingCapacitiesOnStops,
maximizeOptionalStops,
maximizePreferredStops,
minimizeLargestTourDuration,
minimizeWorkingDuration,
minimizeDistance,
minimizeEarlyLoadings
​
maxOptimizationDuration
string

Maximum time the engine is allowed to search, in ISO 8601 duration format. The engine stops early on its own once it stops finding improvements, so an overly generous value costs only a longer worst case, never a worse solution.

Default. If omitted, 5 seconds for the sandbox agency and 15 minutes for the production agency. A value exceeding the agency's maximum (5 seconds for the sandbox, 6 hours for production by default) is clamped to it, with a warning in the response; see Limits and quotas.

Modelling pitfall. A good solution typically takes about PT10S for 1 resource and 15 stops, PT2M for 5 resources and 100 stops, PT10M for 30 resources and 800 stops, and PT30M for 45 resources and 3,000 stops. These values are indicative, not a guarantee: a plan can converge faster or slower depending on its constraints, and past about 800 stops the 15-minute production default is too short. Size this value against your own data (see Handling large volumes).

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

"PT1H"

​
tz
string

Time zone this plan's resources and stops are scheduled in.

Example:

"Europe/Paris"

​
lateDeparture
boolean
default:false

Allows resources to depart later than the earliest feasible moment in their workingTimeWindow, when doing so does not hurt the objectives.

Default. false: resources always leave as early as possible.

​
sharedCapacities
boolean
default:false

Pools a capacity key across all of a resource's assigned stops for the whole tour, instead of only within a single order.

When to use. For several different orders assigned to the same resource that draw down and top back up the same running balance, such as a limited stock of reusable equipment. Pair it with an atLeastOneValidCapacity additional constraint whenever the rule is stronger than "never exceed the ceiling at any single point".

Default. false: capacities only interact within a single order.

​
emptyThresholdByCapacityByResourceTag
object

Thresholds for capacities below which a resource is considered "empty" for empty distance calculation, grouped by resource tag. A resource is "empty" (kilometres travelled 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 created.

A single plan wrapped with its identifying metadata, as returned by the plan-retrieval endpoints.

​
item
object

The plan itself.

​
agencyId
string

Identifier of the Kardinal tenant/account the plan is scoped to, derived automatically from the access token used to make the request.

Modelling pitfall. Not a physical-depot or site partition key. A single fleet based at several physical depots is still one Plan; do not split it into several Plan objects just because resources have different departure/arrival positions.

Pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$
Example:

"BLD1234567_production"

​
planId
string<uuid>
read-only

The plan id.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
Example:

"4cbd0ab8-282c-4b30-b981-29e1ed8a2016"

​
planVersion
integer

The plan version.

Required range: x >= 1
Example:

42

​
warnings
object[]

Amendments applied while processing this request, if any.