> ## Documentation Index > Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a plan > The plan id is generated by the service: an `id` sent in the payload is ignored and replaced by a generated one. Use the id returned in the response to address the plan on the other endpoints. This operation consumes credits — see [Pricing and credits](https://developers.kardinal.ai/reference/pricing-and-credits). ## OpenAPI ````yaml /openapi.yaml post /plans openapi: 3.0.3 info: title: Kardinal Route Optimization API version: 1.0.1 description: > This document specifies the REST API of Kardinal for builder users. Every endpoint applies to the single agency carried by the access token (either the sandbox agency or the production agency), which is why no agency id appears in the paths. An access token that does not grant access to exactly one agency is rejected with a `403`. This single-agency shape is specific to **builder** users, the audience of this document. A builder account is created through self-service sign-up and always has exactly two agencies, `sandbox` and `production` — one per environment. This differs from a **standard** Kardinal user, who may belong to a pre-existing set of agencies of any size and receives a single access token scoped accordingly, rather than one token per environment. A `429` response with an empty body signals a temporary overload, not a quota: retry after a pause, with an increasing delay between attempts. See [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas). ## Terminology A few everyday terms map to specific fields in this API. Reusing the API's own vocabulary in integration code and support requests avoids ambiguity: - **Route:** the ordered sequence of stops a single resource performs within a plan's solution. Called a `tour` in the API response (`item.tours[]`, with `resourceId`, `distanceInKm`, `workingDuration`, and `wayPoints`). "Route" is the everyday term; `tour` is the field name you'll see in payloads. - **Route plan** (or just "plan"): the full request submitted for optimization (`resources`, `orders`, and any plan-level constraints or objectives). Called `Plan` in this API. Submitting a plan doesn't return a route directly; it returns a `Solution` object (under `item`) containing one tour per resource. - **Disruption:** an event during execution that invalidates part of an already-computed solution and calls for a new one: a delay, a cancellation, or an urgent new order, typically. A disruption is handled by re-optimizing the affected plan (see "Re-optimization" below), not by starting a new one. - **Re-optimization:** submitting an update to a plan that already has a solution (`PUT /plans/{planId}`), using the *same* `id` (the `version` is incremented, and the plan re-optimized, only if its content changed; a `PUT` identical to the stored plan changes nothing and isn't billed). The engine treats this as "same problem, updated data" (the update still carries the complete plan, not only the changes): it repairs the previous solution, adjusting it just enough to be valid for the new data, then keeps improving from there, rather than searching from scratch. - **Delivery window:** the time window during which a `delivery`-kind stop should or must be visited: `authorizedTimeWindows` (hard: outside of it, the stop can't be planned at all) or `preferredTimeWindows` (soft: reachable outside it, at the cost of the `minimizeDelay` objective). contact: url: https://kardinal.ai/ email: customer.success@kardinal.ai servers: - url: https://app.kardinal.ai/api/v2 description: >- Production and sandbox (same host; the API token used determines which agency a call applies to). - url: /api/v2 description: Relative path, for environments where the host is supplied separately. security: - access_token: [] tags: - name: Plan description: How to create, retrieve, update, and delete plans. - name: Solution description: How to retrieve the solution of a plan and its objectives. - name: Webhook description: >- How to register, retrieve, update, and delete plan webhooks, and inspect their delivery results. paths: /plans: post: tags: - Plan summary: Create a plan description: > The plan id is generated by the service: an `id` sent in the payload is ignored and replaced by a generated one. Use the id returned in the response to address the plan on the other endpoints. This operation consumes credits — see [Pricing and credits](https://developers.kardinal.ai/reference/pricing-and-credits). operationId: postPlan requestBody: description: The plan to create. content: application/json: schema: $ref: '#/components/schemas/Plan' examples: minimalPlan: summary: Minimal plan (one resource, three pickup-only orders) value: resources: - id: resource1 vehicleProfile: type: fly kmph: 20 workingTimeWindow: begin: '2026-03-21T08:00:00Z' end: '2026-03-21T23:00:00Z' orders: - id: order-1 stops: - type: single id: Balard position: lon: 2.279424 lat: 48.835749 kind: pickup operationDuration: PT5M30S - id: order-2 stops: - type: single id: Dauphine position: lon: 2.274264 lat: 48.870087 kind: pickup operationDuration: PT5M30S - id: order-3 stops: - type: single id: Station-f position: lon: 2.370564 lat: 48.83476 kind: pickup operationDuration: PT5M30S maxOptimizationDuration: PT1M responses: '201': description: Plan response created. content: application/json: schema: $ref: '#/components/schemas/EnvelopedPlan' examples: minimalPlan: summary: Response for the minimal plan example value: item: id: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016 agencyId: BLD1234567_production version: 1 status: waitingRoom: waitingVersion: 1 runningVersion: 1 creation: waitingVersion: 1 runningVersion: 1 optimization: waitingVersion: 1 runningVersion: 1 resources: - id: resource1 vehicleProfile: type: fly kmph: 20 workingTimeWindow: begin: '2026-03-21T08:00:00Z' end: '2026-03-21T23:00:00Z' orders: - id: order-1 stops: - type: single id: Balard position: lon: 2.279424 lat: 48.835749 kind: pickup operationDuration: PT5M30S - id: order-2 stops: - type: single id: Dauphine position: lon: 2.274264 lat: 48.870087 kind: pickup operationDuration: PT5M30S - id: order-3 stops: - type: single id: Station-f position: lon: 2.370564 lat: 48.83476 kind: pickup operationDuration: PT5M30S agencyId: BLD1234567_production planId: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016 planVersion: 1 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthenticated' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: Plan: type: object description: >- A full plan for a date and agency, with its associated resources, orders, constraints, and so on. properties: id: readOnly: true allOf: - $ref: '#/components/schemas/PlanId' agencyId: readOnly: true allOf: - $ref: '#/components/schemas/AgencyId' version: readOnly: true allOf: - $ref: '#/components/schemas/PlanVersion' running: type: boolean description: To know if the plan is running. readOnly: true status: readOnly: true allOf: - $ref: '#/components/schemas/PlanStatus' state: description: > Current optimization state of the plan (see `PlanState`). Does not carry the solution itself — once `optimized`, retrieve it separately via `GET /plans/{planId}/solution`. readOnly: true allOf: - $ref: '#/components/schemas/PlanState' properties: allOf: - $ref: '#/components/schemas/Properties' resources: type: array description: > 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](https://developers.kardinal.ai/reference/limits-and-quotas). items: allOf: - $ref: '#/components/schemas/Resource' nbResources: type: integer description: Number of entries in `resources`, computed by the server. minimum: 0 readOnly: true orders: type: array description: > 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](https://developers.kardinal.ai/reference/limits-and-quotas). items: allOf: - $ref: '#/components/schemas/Order' nbOrders: type: integer description: Number of entries in `orders`, computed by the server. minimum: 0 readOnly: true additionalOperationDurations: type: array description: >- Additional operation time for a resource and a stop, according to tags (pairs of tags must be unique). uniqueItems: true items: allOf: - $ref: '#/components/schemas/AdditionalOperationDuration' operationDurationPoliciesByResourceTag: type: object description: Policies to remove the operation durations, by resource tag. additionalProperties: type: array items: allOf: - $ref: '#/components/schemas/OperationDurationPolicy' example: trailer: - policy: withoutFirstOperationDuration stopTags: - access:parking33 additionalConstraints: type: array description: >- Extra constraints layered on top of resources' and orders' own fields, such as forbidden assignments or capacity ceilings shared across a group of stops. items: oneOf: - $ref: >- #/components/schemas/AdditionalConstraintAtLeastOneValidCapacity - $ref: '#/components/schemas/AdditionalConstraintForbiddenAssignment' - $ref: '#/components/schemas/AdditionalConstraintIncompatibleStopTags' - $ref: '#/components/schemas/AdditionalConstraintAtLeastOneConstraint' - $ref: '#/components/schemas/AdditionalConstraintCapacities' - $ref: '#/components/schemas/AdditionalConstraintMaxStopTagGroups' - $ref: '#/components/schemas/AdditionalConstraintRemovalStrategy' discriminator: propertyName: type mapping: atLeastOneValidCapacity: >- #/components/schemas/AdditionalConstraintAtLeastOneValidCapacity forbiddenAssignment: '#/components/schemas/AdditionalConstraintForbiddenAssignment' incompatibleStopTags: '#/components/schemas/AdditionalConstraintIncompatibleStopTags' atLeastOneConstraint: '#/components/schemas/AdditionalConstraintAtLeastOneConstraint' capacities: '#/components/schemas/AdditionalConstraintCapacities' maxStopTagGroups: '#/components/schemas/AdditionalConstraintMaxStopTagGroups' removalStrategy: '#/components/schemas/AdditionalConstraintRemovalStrategy' globalConstraints: type: array description: List of global constraints to be satisfied by the returned solution. items: oneOf: - $ref: '#/components/schemas/GlobalConstraintMaxCumulatedCost' discriminator: propertyName: type mapping: maxCumulatedCost: '#/components/schemas/GlobalConstraintMaxCumulatedCost' accessDurationsByStopTag: type: object description: > 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. additionalProperties: allOf: - $ref: '#/components/schemas/Duration' example: access:parking33: PT5M overlappingCapacitiesByStopTag: type: object description: > 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. additionalProperties: type: integer example: capa:bat22: 3 setupDurations: type: array description: >- Sequence-dependent changeover times to add whenever a resource travels directly between two stops carrying a matching pair of tags. items: allOf: - $ref: '#/components/schemas/SetupDuration' objectives: description: >- Objectives the engine optimizes for this plan; see `PlanObjectives` for how priority order drives trade-offs. allOf: - $ref: '#/components/schemas/PlanObjectives' maxOptimizationDuration: description: > 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](https://developers.kardinal.ai/reference/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](https://developers.kardinal.ai/guides/handling-large-volumes#sizing-maxoptimizationduration-for-a-large-problem)). allOf: - $ref: '#/components/schemas/Duration' example: PT1H tz: description: Time zone this plan's resources and stops are scheduled in. allOf: - $ref: '#/components/schemas/TimeZone' createdAt: description: The plan's creation datetime. readOnly: true allOf: - $ref: '#/components/schemas/DateTime' createdBy: type: string description: The username of the user who created this plan. readOnly: true example: jane.doe updatedAt: description: >- The plan's last update datetime: absent until the plan is updated for the first time. readOnly: true allOf: - $ref: '#/components/schemas/DateTime' updatedBy: type: string description: >- The username of the user who last updated this plan: absent until the plan is updated for the first time. readOnly: true example: jane.doe archivedAt: description: >- The plan's archiving datetime: if this property is present, the plan is archived. readOnly: true allOf: - $ref: '#/components/schemas/DateTime' lateDeparture: description: > 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. type: boolean default: false sharedCapacities: description: > 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. type: boolean default: false emptyThresholdByCapacityByResourceTag: description: > 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. type: object additionalProperties: allOf: - $ref: '#/components/schemas/Capacities' example: heavy: weight: 150 volume: 75 '*': weight: 50 avoidEarlyLoadingsByResourceTag: type: object description: > 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. additionalProperties: type: array items: allOf: - $ref: '#/components/schemas/AvoidEarlyLoading' example: '*': - stopTag: depot1 capacities: - weight - volume heavy: - stopTag: warehouse CO2EmissionCalculationByResourceTag: type: object description: > 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. additionalProperties: allOf: - $ref: '#/components/schemas/Cost' example: resTag2: km: costCoeff: 0.55 costPerCapacityPerTravelledKm: weight: costCoeff: 0.2 required: - resources EnvelopedPlan: type: object description: >- A single plan wrapped with its identifying metadata, as returned by the plan-retrieval endpoints. properties: item: description: The plan itself. allOf: - $ref: '#/components/schemas/Plan' agencyId: allOf: - $ref: '#/components/schemas/AgencyId' planId: $ref: '#/components/schemas/PlanId' planVersion: allOf: - $ref: '#/components/schemas/PlanVersion' warnings: type: array description: Amendments applied while processing this request, if any. items: allOf: - $ref: '#/components/schemas/Warning' PlanId: description: The plan id. readOnly: true example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016 allOf: - $ref: '#/components/schemas/UUID' AgencyId: type: string description: > 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. readOnly: true pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$ example: BLD1234567_production PlanVersion: type: integer description: The plan version. readOnly: true minimum: 1 example: 42 PlanStatus: type: object readOnly: true description: >- Fine-grained progress of the plan through the optimization pipeline, broken down by stage. properties: planVersionInSolution: description: The plan version taken into account in the current solution. allOf: - $ref: '#/components/schemas/PlanVersion' waitingRoom: description: >- If the maximum number of simultaneous running plans has already been reached, the plan waits in the waiting room for one of the running plans to finish. allOf: - $ref: '#/components/schemas/PlanStatusVersion' waitingTraffic: description: The plan is waiting for its traffic coefficients to be computed. allOf: - $ref: '#/components/schemas/PlanStatusVersion' creation: description: The plan is being created to be optimized. allOf: - $ref: '#/components/schemas/PlanStatusVersion' optimization: description: The plan is being optimized. allOf: - $ref: '#/components/schemas/PlanStatusVersion' PlanState: type: string readOnly: true description: > 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 cancelled. - deleted: The plan was deleted and awaiting optimizations were cancelled. - interrupted: The plan was either updated, stopped, or deleted during its optimization. enum: - waiting - processing - preOptimizing - preOptimized - optimizing - optimized - stopped - deleted - interrupted Properties: type: object description: > 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. additionalProperties: type: string example: plate: AB-123-CD driverName: Jane Doe Resource: type: object description: > A vehicle-driver pair for the duration of the plan. Only `id`, `vehicleProfile`, and `workingTimeWindow` are required; everything else defaults to "unconstrained". `capacities`, `skills`, and `tags` are all free-form: the API doesn't predefine `weight` or `forklift` as special values. Whatever keys are used on a resource must match the keys used on the stops/orders it is expected to serve. properties: id: description: Resource ids must be unique within a plan. example: resource1 allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: allOf: - $ref: '#/components/schemas/Properties' state: allOf: - $ref: '#/components/schemas/State' cost: description: >- Custom cost model (per km, per capacity unit, fixed cost) used by the `minimizeCosts` objective. allOf: - $ref: '#/components/schemas/Cost' CO2EmissionCalculation: description: > Optional CO2 emission calculation parameters for this resource. The object is `Cost`-shaped. Typical fields: - `km`: emission per travelled kilometre (for example `costCoeff` in g/km); - `costPerCapacityPerTravelledKm`: per-capacity emission per travelled kilometre; - `costPerCapacityPerTravelledHour`: per-capacity emission per travel hour (travel duration only). When set, the resulting emissions are reported on the tour as `CO2Emission`. Takes precedence over any matching plan-level declaration. allOf: - $ref: '#/components/schemas/Cost' example: km: costCoeff: 0.55 costPerCapacityPerTravelledKm: weight: costCoeff: 0.2 costPerCapacityPerTravelledHour: weight: costCoeff: 0.05 priority: description: > Relative importance of the resource; lower is more important, and the value can be negative. > **When to use.** Used by `minimizeResources` to decide which resources to leave unused first under fleet pressure: it minimizes the least important resources first (highest number), so they're the first left unused. type: integer default: 0 example: 0 skills: description: >- Qualifications this resource has. Matched against an order's `requiredSkills`. type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - forklift - truck preferredStopTags: description: > Soft counterpart to `skills`/`requiredSkills`, used with the `maximizePreferredStops` objective. > **When to use.** For a preference between resources, not a hard requirement. Use `skills`/`requiredSkills` instead when a resource must have the qualification. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - access:parking33 - capa:bat22 - setup:france tags: description: > Free-form tags, referenced by plan-level mechanisms (`additionalConstraints`, `costsByResourceTag`, `accessDurationsByStopTag`, and so on). type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - trailer vehicleProfile: description: > Mode of transport and its travel constraints. Each type exposes different parameters; `truck` is the richest (weight, dimensions, hazardous goods, toll/tunnel/highway avoidance). See the individual `VehicleProfile*` schemas for the full parameter list of each mode. oneOf: - $ref: '#/components/schemas/VehicleProfileFly' - $ref: '#/components/schemas/VehicleProfilePedestrian' - $ref: '#/components/schemas/VehicleProfileBicycle' - $ref: '#/components/schemas/VehicleProfileScooter' - $ref: '#/components/schemas/VehicleProfileMotorbike' - $ref: '#/components/schemas/VehicleProfileCar' - $ref: '#/components/schemas/VehicleProfileTruck' discriminator: propertyName: type mapping: fly: '#/components/schemas/VehicleProfileFly' pedestrian: '#/components/schemas/VehicleProfilePedestrian' bicycle: '#/components/schemas/VehicleProfileBicycle' scooter: '#/components/schemas/VehicleProfileScooter' motorbike: '#/components/schemas/VehicleProfileMotorbike' car: '#/components/schemas/VehicleProfileCar' truck: '#/components/schemas/VehicleProfileTruck' capacities: description: >- Capacity ceilings available on this resource. See the `Capacities` schema. allOf: - $ref: '#/components/schemas/Capacities' departure: description: > Start coordinates of the resource's route, typically a depot. If omitted, the working day starts at the first visited stop instead. > **Modelling pitfall.** Depots are not first-class objects in this API. Resolve a depot to its `{lat, lon}` position on the client side before building the plan. allOf: - $ref: '#/components/schemas/Position' arrival: description: > End coordinates of the resource's route, typically a depot, as a raw `{lat, lon}` position (see `departure`). If omitted, the working day ends at the last visited stop instead. > **When to use.** Set this to the literal string `"atFirstPosition"` instead of a position to make the resource return to wherever its tour actually started, rather than to a separate fixed point. oneOf: - $ref: '#/components/schemas/Position' - $ref: '#/components/schemas/AtFirstPositionArrival' workingTimeWindow: description: > Time window during which the resource is available to work. Often paired with `maxWorkingDuration`, since a wide window does not by itself mean a long shift. > **Modelling pitfall.** Spanning more than one calendar day does not, on its own, force any rest between working days. Encode daily rest explicitly in `breaks[]`, for example a `travelDurationSlidingBreak` sized for a full night's rest, or one `timeWindowBreak` per calendar day the plan spans. allOf: - $ref: '#/components/schemas/TimeWindow' example: begin: '2026-03-17T08:00:00+01:00' end: '2026-03-17T18:00:00+01:00' maxWorkingDuration: description: >- Maximum working time (travel, service, breaks and waiting combined) inside `workingTimeWindow`, in ISO 8601 duration format. allOf: - $ref: '#/components/schemas/Duration' example: PT8H maxDistanceInKm: description: >- Maximum total distance the resource may travel over the plan, in kilometres. Constrains its service area. type: number example: 200 maxInterStopDistanceInKm: description: > Maximum distance between two consecutive stops on a tour, in kilometres. Either a scalar value applied uniformly to every travel of the tour, or a structured object with independent bounds per segment (`firstTravel`, `interStop`, `lastTravel`). > **Default.** Each key of the structured form is independent; an absent key means no constraint on that segment, not a constraint set to zero. oneOf: - type: number description: >- Uniform bound, in kilometres, applied to every travel of the tour. example: 50 - $ref: '#/components/schemas/MaxInterStopDistanceInKmBounds' maxInterStopDuration: description: > Maximum duration between two consecutive stops on a tour. Either a single duration applied uniformly to every travel of the tour, or a structured object with independent bounds per segment (`firstTravel`, `interStop`, `lastTravel`). > **Default.** Each key of the structured form is independent; an absent key means no constraint on that segment, not a constraint set to zero. oneOf: - $ref: '#/components/schemas/Duration' - $ref: '#/components/schemas/MaxInterStopDurationBounds' breaks: description: >- Breaks to schedule into this resource's tour; see `Break` for the three available kinds. type: array items: $ref: '#/components/schemas/Break' operationDurationPolicies: description: >- Policies excluding specific operation durations from this resource's tour; see `OperationDurationPolicy`. type: array items: allOf: - $ref: '#/components/schemas/OperationDurationPolicy' travelTimeCoefficient: description: >- Multiplier applied to every network-computed travel time for this resource, to account for a systematically slower or faster driver. type: number format: float example: 1.05 emptyThresholdByCapacity: description: > Thresholds for capacities below which a resource is considered "empty" for empty distance calculation. A resource is "empty" (kilometres travelled count as empty distance) when all capacities are at or below their threshold. allOf: - $ref: '#/components/schemas/Capacities' example: weight: 100 volume: 50 avoidEarlyLoadings: type: array description: >- Early loading declarations for this resource. Each entry identifies a stop tag and optional capacities used to compute the `minimizeEarlyLoadings` objective. items: allOf: - $ref: '#/components/schemas/AvoidEarlyLoading' required: - id - vehicleProfile - workingTimeWindow Order: type: object description: > One or more `stops` that must all be planned onto the *same* resource, in array order (position in the array acts as a precedence constraint). Only `id` and `stops` are required. properties: id: description: Order ids must be unique within a plan. example: order1 allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: allOf: - $ref: '#/components/schemas/Properties' priority: description: > Relative importance of the order; lower is more important, and the value can be negative. > **When to use.** Lower an order's priority, or mark it `optional`, to make an acceptable-to-drop trade-off explicit rather than an unplanned side effect once the fleet is under pressure from higher-priority stops. > **Modelling pitfall.** Priority levels are strict tiers, not weights: one more planned stop of a more important level outweighs any number of stops of a less important level. type: integer default: 0 example: 0 optional: description: > If `true`, the order leaves the `maximizeMandatoryStops` objective: it can be left unplanned without affecting it, and is only placed if `maximizeOptionalStops` is in the plan's objectives. Without that objective it's unlikely to be planned, since it adds cost (distance, duration) without serving any higher-ranked objective. > **Modelling pitfall.** Not the same as a very low `priority`: a mandatory order, however low its priority, still counts towards `maximizeMandatoryStops`. type: boolean requiredSkills: description: > Hard requirement: a resource must have every listed skill to be assignable to this order. type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - forklift - truck stops: description: > The stops making up this order; see `Stop` for a single fixed stop vs. a group of alternatives. > **Default.** Capped at 3,000 stops per plan across all orders combined — see [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas). type: array uniqueItems: true items: $ref: '#/components/schemas/Stop' successiveStops: description: > The order's stops must be visited consecutively, with nothing from another order in between. Mutually exclusive with `maxStopSpan`. > **Default.** An order without `successiveStops` can have at most 4 stops; see [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas). type: boolean maxStopSpan: description: > Maximum time allowed to elapse between the order's stops (for example between a pickup and its delivery), without forcing them to be consecutive. allOf: - $ref: '#/components/schemas/Duration' required: - id - stops AdditionalOperationDuration: type: object description: Additional operation duration by stop tag and resource tag. properties: resourceTag: type: string description: Resource tag. example: trailer allOf: - $ref: '#/components/schemas/RegexIdValidation' stopTag: type: string description: Stop tag. example: heavy allOf: - $ref: '#/components/schemas/RegexIdValidation' additionalOperationDuration: description: >- Extra duration added on top of the stop's own `operationDuration` whenever this `resourceTag`/`stopTag` pair is matched. allOf: - $ref: '#/components/schemas/Duration' required: - resourceTag - stopTag - additionalOperationDuration OperationDurationPolicy: type: object description: >- Policy to indicate which operation duration must not be taken into account. properties: policy: type: string description: > Which operation duration to leave out of the schedule: `withoutFirstOperationDuration` ignores only the first matching stop's operation duration, `withoutOperationDurations` ignores it on every matching stop. enum: - withoutFirstOperationDuration - withoutOperationDurations stopTags: type: array description: Stop tags this policy applies to. items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - access:parking33 - capa:bat22 - setup:france required: - policy AdditionalConstraintAtLeastOneValidCapacity: type: object description: > `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. properties: type: description: >- Discriminator identifying this constraint as `atLeastOneValidCapacity`. type: string enum: - atLeastOneValidCapacity name: description: >- Name identifying this constraint, referenced by any resulting `AtLeastOneValidCapacityViolation`. type: string example: capacityCheck1 capacities: description: Capacity thresholds; at every stop, at least one of these must hold. allOf: - $ref: '#/components/schemas/Capacities' resourceTags: description: Resource tags this constraint applies to. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB required: - type - capacities AdditionalConstraintForbiddenAssignment: type: object description: > `additionalConstraints` scope. Bars a specific resource tag from a specific stop tag: a targeted exclusion, narrower than `incompatibleStopTags`. properties: type: description: Discriminator identifying this constraint as `forbiddenAssignment`. type: string enum: - forbiddenAssignment name: description: >- Name identifying this constraint, referenced by any resulting `ForbiddenAssignmentViolation`. type: string example: noTrailerAtWarehouse resourceTag: type: string description: Resource tag. example: trailer allOf: - $ref: '#/components/schemas/RegexIdValidation' stopTag: type: string description: Stop tag. example: heavy allOf: - $ref: '#/components/schemas/RegexIdValidation' required: - type - resourceTag - stopTag AdditionalConstraintIncompatibleStopTags: type: object description: > `additionalConstraints` scope. Two stop tags can never appear in the same tour, regardless of resource. properties: type: description: Discriminator identifying this constraint as `incompatibleStopTags`. type: string enum: - incompatibleStopTags name: description: >- Name identifying this constraint, referenced by any resulting `StopIncompatibilityViolation`. type: string example: noOverlap1 stopTags: allOf: - $ref: '#/components/schemas/StopTagPair' resourceTags: description: Resource tags this constraint applies to. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB required: - type - stopTags AdditionalConstraintAtLeastOneConstraint: type: object description: > `additionalConstraints` scope. Combines several constraints with OR logic: the tour is valid if at least one of `constraints` is satisfied. properties: type: description: Discriminator identifying this constraint as `atLeastOneConstraint`. type: string enum: - atLeastOneConstraint name: description: >- Name identifying this constraint, referenced by any resulting `AtLeastOneConstraintViolation`. type: string example: orConstraint1 constraints: description: >- Constraints combined with OR logic; the tour is valid if at least one is satisfied. type: array items: oneOf: - $ref: >- #/components/schemas/AdditionalConstraintAtLeastOneValidCapacity - $ref: '#/components/schemas/AdditionalConstraintForbiddenAssignment' - $ref: '#/components/schemas/AdditionalConstraintIncompatibleStopTags' - $ref: '#/components/schemas/AdditionalConstraintAtLeastOneConstraint' - $ref: '#/components/schemas/AdditionalConstraintCapacities' - $ref: '#/components/schemas/AdditionalConstraintMaxStopTagGroups' - $ref: '#/components/schemas/AdditionalConstraintRemovalStrategy' discriminator: propertyName: type mapping: atLeastOneValidCapacity: >- #/components/schemas/AdditionalConstraintAtLeastOneValidCapacity forbiddenAssignment: '#/components/schemas/AdditionalConstraintForbiddenAssignment' incompatibleStopTags: '#/components/schemas/AdditionalConstraintIncompatibleStopTags' atLeastOneConstraint: '#/components/schemas/AdditionalConstraintAtLeastOneConstraint' capacities: '#/components/schemas/AdditionalConstraintCapacities' maxStopTagGroups: '#/components/schemas/AdditionalConstraintMaxStopTagGroups' removalStrategy: '#/components/schemas/AdditionalConstraintRemovalStrategy' required: - type - constraints AdditionalConstraintCapacities: type: object description: > `additionalConstraints` scope. Fine-grained capacity constraint beyond the base resource/stop matching, valid if all the listed capacities are satisfied. Unlike the other `additionalConstraints` types, it does not currently surface a named violation in the solution; use it as a member of `atLeastOneConstraint`, not on its own at the top level of `additionalConstraints`. properties: type: description: Discriminator identifying this constraint as `capacities`. type: string enum: - capacities name: description: >- Name identifying this constraint. No violation is currently reported for this constraint type. type: string example: capacityLimit1 capacities: description: Capacities that must be satisfied. allOf: - $ref: '#/components/schemas/Capacities' resourceTag: type: string description: Resource tag. example: trailer allOf: - $ref: '#/components/schemas/RegexIdValidation' required: - type - capacities - resourceTag AdditionalConstraintMaxStopTagGroups: type: object description: > `additionalConstraints` scope. Caps how many separate visits to stops sharing a tag a resource can make. > **When to use.** For limiting depot returns, or forcing a shared-equipment tag to stay with a single resource across the tour. If the tour has stops whose `stopTags` constitute too many groups, the tour is invalid. properties: type: type: string description: Discriminator identifying this constraint as `maxStopTagGroups`. enum: - maxStopTagGroups name: type: string description: >- Name identifying this constraint, referenced by any resulting `MaxStopTagGroupsViolation`. example: maxDepotVisits resourceTags: description: Resource tags this constraint applies to. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB maxGroupsByStopTag: description: Maximum number of separate visit groups allowed, by stop tag. allOf: - $ref: '#/components/schemas/MaxGroupsByStopTag' required: - type - maxGroupsByStopTag AdditionalConstraintRemovalStrategy: type: object description: > `additionalConstraints` scope. Enforces a last-in-first-out unloading order on a resource: with `removalStrategy: "lifo"`, a resource can only unload the last thing it loaded. Not a rule about which stops get dropped from an over-constrained plan. > **When to use.** For a stacked or sequential-loading vehicle, such as a car carrier loading vehicles nose-to-tail on a single deck, or a multi-deck cage truck, where physically nothing can be unloaded except the item that went on last. Set it on the resource tag or tags representing that vehicle class. properties: type: description: Discriminator identifying this constraint as `removalStrategy`. type: string enum: - removalStrategy name: description: >- Name identifying this constraint, referenced by any resulting `RemovalStrategyViolation`. type: string example: lifoRule1 resourceTags: description: Resource tags this constraint applies to. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB capacities: description: Capacity names tracked for the last-in-first-out ordering. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - volume - length removalStrategy: type: string allOf: - $ref: '#/components/schemas/RemovalStrategyType' example: lifo required: - type GlobalConstraintMaxCumulatedCost: type: object description: > `globalConstraints` scope (whole fleet, not just one tour). Caps a cost total (for example number of active resources in a tag group) across the whole fleet. Provides an upper bound on the cost of specified resources. properties: type: description: Discriminator identifying this constraint as `maxCumulatedCost`. type: string enum: - maxCumulatedCost name: description: >- Name identifying this constraint, referenced by any resulting `GlobalViolationMaxCumulatedCost`. type: string example: fleetCostCap maximum: description: The constraint's maximum allowed cumulated cost. type: number example: 1000 costsByResourceTag: allOf: - $ref: '#/components/schemas/CostsByResourceTag' required: - type - costsByResourceTag Duration: type: string description: 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 SetupDuration: type: object description: >- Extra changeover duration inserted when a resource travels directly from a stop tagged `fromStopTag` to a stop tagged `toStopTag`. properties: fromStopTag: type: string description: Tag of the stop the resource is leaving. example: setup:france allOf: - $ref: '#/components/schemas/RegexIdValidation' toStopTag: type: string description: Tag of the stop the resource is arriving at next. example: setup:belgium allOf: - $ref: '#/components/schemas/RegexIdValidation' setupDuration: description: >- Changeover duration added between the two stops, in ISO 8601 duration format. allOf: - $ref: '#/components/schemas/Duration' required: - fromStopTag - toStopTag - setupDuration PlanObjectives: type: array description: > Ordered list of objectives the engine pursues in strict lexicographic priority: it first searches for the best possible value of the first objective, then, among solutions tied on that value, optimizes the second, and so on down the list. Each entry is either a name from `ObjectivesEnum`, a `maximizePrecedences` object, or a `custom` object. `maximizeMandatoryStops`, `maximizeOptionalStops`, and `minimizeResources` are split into one objective per `priority` value present in the plan, kept at the position of the original objective: stops are maximized from the most important level (lowest number) down, resources are minimized from the least important level (highest number) up. > **When to use.** Reorder the list to change which objective the engine favours when two cannot both be improved at once, for example moving `minimizeCosts` ahead of `minimizeDistance` when cost matters more than raw kilometres for this fleet. > **Modelling pitfall.** Because priority is lexicographic rather than weighted, reordering the list can change the chosen solution even when every objective's value looks comparable; moving an objective earlier makes the engine trade off later objectives to protect it, not merely break ties differently. items: oneOf: - $ref: '#/components/schemas/ObjectivesEnum' - $ref: '#/components/schemas/MaximizePrecedencesObjective' - $ref: '#/components/schemas/CustomObjective' default: - maximizeMandatoryStops - minimizeDelay - minimizeCosts - minimizeResources - minimizeOverOverlappingCapacitiesOnStops - maximizeOptionalStops - maximizePreferredStops - minimizeWorkingDuration - minimizeDistance TimeZone: type: string description: > IANA time zone identifier (the "tz database"), used to interpret a local datetime that has no explicit UTC offset. A datetime can always be given in ISO 8601 with an explicit offset or `Z`, for example these three values for the same instant: `2025-05-22T05:43:00Z`, `2025-05-22T06:43:00+01:00`, `2025-05-22T07:43:00+02:00`. Pairing a local datetime with a `tz` value is a more human-readable alternative input: `2025-05-22 07:43` with `tz: "Europe/Paris"` denotes that same instant, and seconds are optional. Where a JSON input object accepts a `tz` property, every local datetime found elsewhere in that same object is converted to ISO 8601 using it before further processing. > **Modelling pitfall.** A `properties` sub-object (free-form client data, see the `Properties` schema) is never scanned for local datetimes, regardless of `tz`. externalDocs: url: https://www.iana.org/time-zones example: Europe/Paris DateTime: type: string description: >- A full calendar date time, expressed in the ISO8601 **date** format: YYYY-MM-DDThh:mm:ssZ. example: '2019-11-15T12:34:56Z' Capacities: type: object description: > Free-form map from a capacity name to a quantity, tracked as its own independent dimension on both resources and stops. For every key a resource declares, the running total never exceeds the resource's value for that key at any point in the tour. A key the stop consumes but the resource doesn't declare is unconstrained on that resource. > **When to use.** For a vehicle carrying exactly one item at a time whose size varies by trip, a count-based ceiling (`{"containers": 1}`) is robust to size variance; a size-based ceiling (`{"volume": }`) is needed only when overflow or partial-load reporting matters. > **Modelling pitfall.** Capacity keys are matched by exact string, with no case-folding. A typo such as `weight` on a resource against `Weight` on a stop raises no error: it silently leaves that dimension unlimited for the stop instead of enforcing the resource's ceiling. additionalProperties: type: number example: volume: 9.5 weight: 2200 nbPackages: 23 AvoidEarlyLoading: type: object description: >- Declares a stop tag and optional capacities for early loading computation. properties: stopTag: type: string description: >- The stop tag identifying stops where early loading should be avoided. example: depot1 allOf: - $ref: '#/components/schemas/RegexIdValidation' capacities: type: array description: >- Capacities to consider. If empty or omitted, all capacities are considered. items: type: string uniqueItems: true required: - stopTag example: stopTag: depot1 capacities: - weight - volume Cost: type: object description: > Cost structure of a resource. Fields are cumulative: the total cost of a tour is the sum of the contributions of every field that is set. > **Modelling pitfall.** Each field applies to a different base. The same cost must be expressed only once; setting both `using` and a `costFloor` on `km` applies a flat cost and a floor to the same distance rather than two independent contributions. properties: workedHours: description: Cost proportional to worked hours, in currency unit per hour. allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' km: description: >- Cost proportional to travelled distance, in currency unit per kilometre. allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' using: description: > Flat cost added once per resource actually used in the plan, in currency unit. > **Modelling pitfall.** Independent of distance, duration, and capacity. A per-kilometre rate belongs in `km`, an hourly rate in `workedHours`. type: number example: 120 costsByStopTag: description: >- Additional cost floors and coefficients applied once per visited stop, by stop tag. type: object additionalProperties: allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' example: warehouse: constantCost: 5 costsByCapacity: description: > Additional cost floors and coefficients on the quantities handled at the tour's stops, by capacity name, further scoped to specific stop tags. Each stop adds the absolute value of its quantity, whatever its `kind` or sign, and floors apply once to the tour total. > **Modelling pitfall.** The base is the quantity handled, not the vehicle's load: loading at departure doesn't count, and a pickup and a delivery of the same 100 units count 200. It applies to any capacity the stops carry, declared on the resource or not, and a guaranteed minimum comes from `constantCost`, not `costFloor`. type: object additionalProperties: allOf: - $ref: '#/components/schemas/TaggedCostFloorsAndCoeffs' example: weight: stopTags: - warehouse costCoeff: 0.1 costPerCapacityPerTravelledKm: type: object description: > Contribution to cost proportional to travelled distance and transported capacity, in currency unit per capacity unit per kilometre (for example `EUR/tonne/km`). For each capacity, the contribution is `costCoeff x distance(km) x transportedCapacity`. > **Default.** Cumulable with `costPerCapacityPerTravelledHour` and with the other cost fields; the two travelled-cost maps are independent. additionalProperties: allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' example: weight: costCoeff: 0.2 volume: costCoeff: 0.1 costPerCapacityPerTravelledHour: type: object description: > Contribution to cost proportional to travel duration and transported capacity, in currency unit per capacity unit per hour (for example `EUR/tonne/h`). For each capacity, the contribution is `costCoeff x travelDuration(h) x transportedCapacity`. > **Modelling pitfall.** The "Travelled" qualifier means travel duration only, not total working time; it does not include service time or waiting. additionalProperties: allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' example: weight: costCoeff: 0.05 Warning: readOnly: true description: > A warning has the same structure as an `Error`, but a different semantic. It is present when an accepted payload was amended — traffic turned off, crow-fly forced, `maxOptimizationDuration` clamped, and so on. The amended field and the applied change are described by `properties.path` and `properties.details`. Warnings can also accompany the errors of a rejected payload: they then describe the amendments applied before the rejecting error was found. > **Modelling pitfall.** Warnings are only returned in the response to the `POST` or `PUT` that produced them. They aren't stored with the plan, so a later `GET` never returns them: read them from that response, since afterwards only the amended value remains visible. allOf: - $ref: '#/components/schemas/Error' EnvelopedErrors: type: object description: >- Envelope wrapping one or more business errors, returned on every error response regardless of HTTP status, except a `429` temporary overload, which comes with an empty body. properties: agencyId: allOf: - $ref: '#/components/schemas/AgencyId' description: > The agency the failed action was scoped to. > **Default.** Absent when the action isn't tied to any agency at all — for example a `401` `NOT_AUTHENTICATED` response, returned before any agency could be resolved from the token. planId: allOf: - $ref: '#/components/schemas/PlanId' description: > The plan the failed action was scoped to. > **Default.** Absent whenever the action concerns an agency but no specific plan, or when `agencyId` itself is absent. errors: type: array description: >- The business errors that occurred. A `400` on plan or resource creation can report several invalid fields at once. items: allOf: - $ref: '#/components/schemas/Error' warnings: type: array description: >- Amendments applied to the payload before the preceding errors were found, if any. items: allOf: - $ref: '#/components/schemas/Warning' example: errors: - code: INVALID_VALUE message: The field value is not valid. UUID: type: string format: uuid description: Universally Unique Identifier. 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: cd4ce4e3-0208-4b10-b346-25f235214e4f readOnly: true PlanStatusVersion: type: object description: >- Which plan version is waiting to enter a given pipeline stage versus already running through it. properties: waitingVersion: description: The version currently waiting. allOf: - $ref: '#/components/schemas/PlanVersion' runningVersion: description: The version currently running. allOf: - $ref: '#/components/schemas/PlanVersion' RegexIdValidation: type: string description: > At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",". Id-uniqueness is scoped per collection, not global: `resources[].id`, `orders[].id`, and `stops[].id` are each their own namespace, so the same string can be reused across `resources`, `orders`, and `stops` in the same plan without a collision. pattern: ^[a-zA-Z0-9-._~:@!$,]+$ State: type: object description: > Resource's current mode and, when re-optimizing a plan whose resources are already underway, the stops, breaks, begin or end already committed to that resource. properties: mode: allOf: - $ref: '#/components/schemas/ResourceMode' assignments: type: array description: > Waypoints to pin onto this resource's tour before the engine plans the rest of it, ordered as they occur on the tour. > **When to use.** For re-optimizing a plan mid-execution: fix the waypoints a resource has already completed or is already committed to, then let the engine re-plan everything that comes after. items: oneOf: - $ref: '#/components/schemas/AssignmentStop' - $ref: '#/components/schemas/AssignmentBegin' - $ref: '#/components/schemas/AssignmentBreak' - $ref: '#/components/schemas/AssignmentEnd' discriminator: propertyName: type mapping: stop: '#/components/schemas/AssignmentStop' begin: '#/components/schemas/AssignmentBegin' break: '#/components/schemas/AssignmentBreak' end: '#/components/schemas/AssignmentEnd' VehicleProfileFly: type: object description: | Crow-fly distance, with no road network. Fastest profile to compute. > **When to use.** For smoke tests only, not real routing. properties: type: description: Discriminator identifying this vehicle profile as `fly`. type: string enum: - fly kmph: description: >- Constant travel speed, in km/h, used to compute crow-fly travel times. type: number example: 60 required: - type VehicleProfilePedestrian: type: object description: Road-network routing for the pedestrian mode. properties: type: description: Discriminator identifying this vehicle profile as `pedestrian`. type: string enum: - pedestrian avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' required: - type VehicleProfileBicycle: type: object description: Road-network routing for the bicycle mode. properties: type: description: Discriminator identifying this vehicle profile as `bicycle`. type: string enum: - bicycle avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidTunnel: description: Excludes tunnels from computed routes. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' required: - type VehicleProfileScooter: type: object description: Road-network routing for the scooter mode. properties: type: description: Discriminator identifying this vehicle profile as `scooter`. type: string enum: - scooter avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidCarShuttleTrain: description: Excludes car-carrying shuttle trains from computed routes. type: boolean avoidTunnel: description: Excludes tunnels from computed routes. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' speedCap: description: >- Maximum travel speed, in km/h, applied to every road segment regardless of its posted speed limit. type: number example: 45 required: - type VehicleProfileMotorbike: type: object description: Road-network routing for the motorbike mode. properties: type: description: Discriminator identifying this vehicle profile as `motorbike`. type: string enum: - motorbike avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidControlledAccessHighway: description: >- Excludes motorways and other controlled-access highways from computed routes. type: boolean avoidCarShuttleTrain: description: Excludes car-carrying shuttle trains from computed routes. type: boolean avoidTunnel: description: Excludes tunnels from computed routes. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' speedCap: description: >- Maximum travel speed, in km/h, applied to every road segment regardless of its posted speed limit. type: number example: 90 required: - type VehicleProfileCar: type: object description: Road-network routing for the car mode. properties: type: description: Discriminator identifying this vehicle profile as `car`. type: string enum: - car withTraffic: description: > Enables predictive traffic in travel-time estimates (billed separately). For any plan where `preferredTimeWindows`/`authorizedTimeWindows` matter, travel-time estimates computed without it are systematically optimistic, which erodes on-time performance against exactly the time windows being targeted. type: boolean avoidTollRoad: description: Excludes toll roads from computed routes. type: boolean avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidControlledAccessHighway: description: >- Excludes motorways and other controlled-access highways from computed routes. type: boolean avoidCarShuttleTrain: description: Excludes car-carrying shuttle trains from computed routes. type: boolean avoidTunnel: description: Excludes tunnels from computed routes. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean avoidUTurns: description: Excludes U-turns from computed routes. type: boolean excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' speedCap: description: >- Maximum travel speed, in km/h, applied to every road segment regardless of its posted speed limit. type: number example: 90 required: - type VehicleProfileTruck: type: object description: > Everything the `car` profile has, plus weight, dimensions, hazardous-goods, and toll/tunnel/highway parameters, for respecting road restrictions on heavy or hazardous-goods vehicles. > **When to use.** A vehicle-type name that is itself an unambiguous heavy-vehicle designation (a truck, lorry, semi-trailer, tractor-trailer, or equivalent) is sufficient evidence to pick `truck` even with no numeric dimensions yet. > **Default.** Setting `type: "truck"` and leaving every truck-only field unset does not apply any default legal-truck-road restriction; routing behaves exactly like `car` until one of those fields is actually set. Default to `car` when a vehicle's dimensions are genuinely unknown, and switch to `truck` once real dimensions or road restrictions are available. properties: type: description: Discriminator identifying this vehicle profile as `truck`. type: string enum: - truck grossWeight: description: >- Gross vehicle weight, in kilograms, used to respect weight-restricted roads. type: number example: 12000 withTraffic: description: > Enables predictive traffic in travel-time estimates (billed separately). For any plan where `preferredTimeWindows`/`authorizedTimeWindows` matter, travel-time estimates computed without it are systematically optimistic, which erodes on-time performance against exactly the time windows being targeted. type: boolean avoidTollRoad: description: Excludes toll roads from computed routes. type: boolean avoidFerry: description: Excludes ferry crossings from computed routes. type: boolean avoidSeasonalClosure: description: Excludes roads that are closed during part of the year. type: boolean avoidControlledAccessHighway: description: >- Excludes motorways and other controlled-access highways from computed routes. type: boolean avoidCarShuttleTrain: description: Excludes car-carrying shuttle trains from computed routes. type: boolean avoidTunnel: description: Excludes tunnels from computed routes. type: boolean avoidDirtRoad: description: Excludes unpaved or dirt roads from computed routes. type: boolean avoidUTurns: description: Excludes U-turns from computed routes. type: boolean shippedHazardousGoods: description: >- Categories of hazardous goods carried, used to respect roads restricted to those categories. type: array items: allOf: - $ref: '#/components/schemas/ShippedHazardousGood' example: - explosive - gas - flammable excludedCountries: description: Countries to route around entirely. allOf: - $ref: '#/components/schemas/CountryCodes' height: description: >- Vehicle height, in metres, used to respect height-restricted roads such as low bridges. type: number example: 4.2 width: description: Vehicle width, in metres, used to respect width-restricted roads. type: number example: 2.5 length: description: Vehicle length, in metres, used to respect length-restricted roads. type: number example: 12 tunnelCategory: allOf: - $ref: '#/components/schemas/TunnelCategory' speedCap: description: >- Maximum travel speed, in km/h, applied to every road segment regardless of its posted speed limit. type: number example: 80 required: - type Position: type: object description: > A `{lat, lon}` geographic coordinate. > **Modelling pitfall.** The API does not geocode addresses; every position submitted must already be a coordinate pair. An incorrectly geocoded position does not raise an error, it silently routes to the wrong place. properties: lon: description: Longitude, in decimal degrees. type: number minimum: -180 maximum: 180 lat: description: Latitude, in decimal degrees. type: number minimum: -90 maximum: 90 required: - lon - lat example: lon: 2.3269331 lat: 48.8812658 AtFirstPositionArrival: type: string description: > The resource must go back to wherever its tour actually started, rather than to a separate fixed point. Only valid as a `Resource.arrival` value, not `departure`. enum: - atFirstPosition TimeWindow: type: object description: > Plain `{begin, end}` window, used for `workingTimeWindow` and break windows. See `TaggedTimeWindow` for the variant used on a stop's `authorizedTimeWindows` / `preferredTimeWindows`. properties: begin: description: Start of the window. allOf: - $ref: '#/components/schemas/DateTime' end: description: End of the window. allOf: - $ref: '#/components/schemas/DateTime' required: - begin - end MaxInterStopDistanceInKmBounds: type: object description: > Per-segment maximum distance, in km, between two consecutive stops on a tour. Each key is independent; an absent key means no constraint on that segment. properties: firstTravel: description: >- Maximum distance, in km, between the resource's departure and the first stop. type: number example: 10 interStop: description: >- Maximum distance, in km, between two consecutive intermediate stops (excluding the first and last travels). type: number example: 25 lastTravel: description: >- Maximum distance, in km, between the last stop and the resource's arrival. type: number example: 15 example: firstTravel: 10 interStop: 25 lastTravel: 15 MaxInterStopDurationBounds: type: object description: > Per-segment maximum duration between two consecutive stops on a tour. Each key is independent; an absent key means no constraint on that segment. properties: firstTravel: description: >- Maximum duration between the resource's departure and the first stop. allOf: - $ref: '#/components/schemas/Duration' interStop: description: >- Maximum duration between two consecutive intermediate stops (excluding the first and last travels). allOf: - $ref: '#/components/schemas/Duration' lastTravel: description: Maximum duration between the last stop and the resource's arrival. allOf: - $ref: '#/components/schemas/Duration' example: firstTravel: PT15M interStop: PT30M lastTravel: PT20M Break: description: > A resource's `breaks` array mixes any of the three types below; they are not mutually exclusive, and a break counts as working time unless its type says otherwise. > **Modelling pitfall.** The two sliding types (`workingDurationSlidingBreak`, `travelDurationSlidingBreak`) count the same physical break toward both their clocks. Define both together for a shift with a labor-time rule and a driving-time rule, rather than assuming one covers the other. > **Default.** For a resource whose `workingTimeWindow` spans more than one calendar day, `breaks` is where daily rest has to be encoded; a wide window does not produce it on its own. oneOf: - $ref: '#/components/schemas/TimeWindowBreak' - $ref: '#/components/schemas/TravelDurationSlidingBreak' - $ref: '#/components/schemas/WorkingDurationSlidingBreak' discriminator: propertyName: type mapping: timeWindowBreak: '#/components/schemas/TimeWindowBreak' travelDurationSlidingBreak: '#/components/schemas/TravelDurationSlidingBreak' workingDurationSlidingBreak: '#/components/schemas/WorkingDurationSlidingBreak' Stop: description: >- Either a single stop or a group of alternative stops, of which the engine picks at most one. oneOf: - $ref: '#/components/schemas/SingleStop' - $ref: '#/components/schemas/AlternativesStop' discriminator: propertyName: type mapping: single: '#/components/schemas/SingleStop' alternatives: '#/components/schemas/AlternativesStop' StopTagPair: type: array description: A pair of incompatible stop tags. items: description: Stop tag. allOf: - $ref: '#/components/schemas/RegexIdValidation' minItems: 2 maxItems: 2 uniqueItems: true example: - goat - cabbage MaxGroupsByStopTag: type: object description: > Free-form map from a stop tag to the maximum number of separate visit groups a resource may make to stops carrying that tag over one tour. additionalProperties: type: integer example: depot: 2 delivery: 10 RemovalStrategyType: type: string description: >- Unloading order enforced by an `AdditionalConstraintRemovalStrategy`. `lifo` is currently the only supported strategy. enum: - lifo default: lifo CostsByResourceTag: type: object description: > Cost structure mapped by resource tag. Unlike `emptyThresholdByCapacityByResourceTag` or `avoidEarlyLoadingsByResourceTag`, the wildcard tag "*" is not supported here — use a named resource tag for every entry. additionalProperties: allOf: - $ref: '#/components/schemas/Cost' example: trailer: using: 120 ObjectivesEnum: type: string description: > 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. enum: - maximizeMandatoryStops - minimizeDelay - minimizeCosts - minimizeResources - minimizeOverOverlappingCapacitiesOnStops - maximizeOptionalStops - maximizePreferredStops - minimizeLargestTourDuration - minimizeWorkingDuration - minimizeDistance - minimizeEarlyLoadings MaximizePrecedencesObjective: type: object description: > Objective that rewards the engine for respecting a set of "this stop tag before that stop tag" precedence pairs, as an entry in `PlanObjectives`. properties: type: type: string description: Discriminator identifying this objective as `maximizePrecedences`. enum: - maximizePrecedences precedences: type: array description: Precedence pairs the engine tries to satisfy as many of as possible. items: allOf: - $ref: '#/components/schemas/StopTagPrecedencePair' disableGroupProximity: type: boolean description: >- If true, disables the group proximity objective that otherwise runs alongside this one. required: - type - precedences CustomObjective: type: object description: > User-defined objective, as an entry in `PlanObjectives`, that optimizes a cost expression built from `costsByResourceTag` in the given `direction` instead of using a built-in objective from `ObjectivesEnum`. properties: type: type: string description: Discriminator identifying this objective as `custom`. enum: - custom name: type: string description: >- Name identifying this custom objective. Must not collide with a built-in `ObjectivesEnum` value. example: minimizeFuelCost not: type: string pattern: >- ^(maximizeMandatoryStops|minimizeDelay|minimizeCosts|minimizeResources|minimizeOverOverlappingCapacitiesOnStops|maximizeOptionalStops|maximizePreferredStops|minimizeLargestTourDuration|minimizeWorkingDuration|minimizeDistance|minimizeEarlyLoadings)$ direction: description: Whether the engine should minimize or maximize the resulting cost. allOf: - $ref: '#/components/schemas/OptimizationDirection' costsByResourceTag: description: Cost expression the engine optimizes, evaluated per resource tag. allOf: - $ref: '#/components/schemas/CostsByResourceTag' required: - type - name - direction - costsByResourceTag CostFloorsAndCoeffs: type: object description: > Cost floor and coefficient for one cost base. A cost cannot be empty. > **Modelling pitfall.** An overcost cannot be set if there is no cost, and `overcostFloor` must be greater than `costFloor`. properties: constantCost: description: Fixed cost added regardless of usage, in currency unit. type: number example: 50 costFloor: description: >- Minimum value of the base (distance, duration, or capacity) below which no cost applies, in the base's own unit. type: number example: 10 costCoeff: description: >- Cost per unit of the base exceeding `costFloor`, in currency unit per base unit. type: number example: 0.2 overcostFloor: description: >- Value of the base beyond which the steeper `overcostCoeff` rate applies instead of `costCoeff`, in the base's own unit. type: number overcostCoeff: description: >- Cost per unit of the base exceeding `overcostFloor`, in currency unit per base unit. type: number example: 0.5 TaggedCostFloorsAndCoeffs: type: object description: >- Cost floor and coefficient (see `CostFloorsAndCoeffs`), further scoped to the stop tags listed in `stopTags`. allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' properties: stopTags: description: > Stop tags this cost applies to. > **Default.** If empty or omitted, the cost applies regardless of stop tag. > **Modelling pitfall.** A tag that no stop carries makes the cost zero, with no error. Floors apply to the total of the matching stops only. type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - warehouse - stop Error: type: object readOnly: true description: > A single business error. Every error response, whatever the HTTP status, wraps one or more `Error` objects in an `EnvelopedErrors` envelope; a single response (typically a `400` on plan/resource creation) can report several invalid fields at once. The one exception is a `429` temporary overload, which comes with an empty body. **Always branch your error handling on `code`, not on the HTTP status alone or on this response's `description` in this spec.** Several `code` values can share the same status. In particular, all of `INVALID_INPUT`, `ID_NOT_UNIQUE`, `KEYS_NOT_UNIQUE`, `INVALID_ID_REFERENCE`, `INVALID_VALUE`, `PRECONDITION_FAILED`, and `NOT_IMPLEMENTED` return `400`. A code's status in the following table applies when that code is returned on its own. A plan that exceeds a size limit of its agency returns a `403` carrying one `INVALID_VALUE` per exceeded limit, each naming the field (`properties.path`) and the limit (`properties.details`), and a single `NOT_ALLOWED`. Read every error in the response, not only the first. ## Business error codes | `code` | HTTP status | Default message | Returned when | | ------------------------ | ----------- | ---------------- | ------------- | | `INVALID_INPUT` | 400 | The payload cannot be parsed. | The request body isn't valid JSON, or doesn't match the expected schema (wrong type, missing required field). | | `ID_NOT_UNIQUE` | 400 | The payload contains a collection with an id repeated multiple times. | A collection in the payload (for example `resources`, `orders`) has the same `id` on more than one item. | | `KEYS_NOT_UNIQUE` | 400 | The payload contains a collection with the keys repeated multiple times. | A collection has a repeated business key other than `id` (for example a tag or reference field expected to be unique). | | `INVALID_ID_REFERENCE` | 400 | The id reference contains an id that does not exist. | A field references an `id` that doesn't match anything else in the payload or system (for example a `resourceId` that doesn't exist). | | `INVALID_VALUE` | 400 | The field value is not valid. | A field's value fails a validation rule: format, range, or allowed values. | | `PRECONDITION_FAILED` | 400 | A precondition failed. | The action requires the target resource to be in a particular state, and it isn't (for example acting on an already-deleted or already-archived object). | | `NOT_IMPLEMENTED` | 400 | Not yet implemented. | The requested behaviour is recognized but not available yet. Despite the name, this returns `400`, not `501`; treat it as a client-facing "not supported" rather than a server capability gap. | | `NOT_AUTHENTICATED` | 401 | The caller is not authenticated. | No access token was sent, or it's missing, malformed, or expired. | | `NOT_ALLOWED` | 403 | The requested action is not allowed. | An agency limit was reached: an optimization quota, a plan size limit, or insufficient credits. `properties.details` states which one. | | `NOT_FOUND` | 404 | The requested object could not be found. | The resource addressed by the URL doesn't exist, or isn't visible to the caller (the API doesn't distinguish the two, to avoid leaking existence of resources you can't access). | | `INTERNAL_SERVER_ERROR` | 500 | The server encountered an unexpected condition that prevented it from fulfilling the request. | Unexpected server-side failure, unrelated to the request's content. If this persists, contact support with the request's timestamp. | This enum reflects the codes returned by the current server implementation. New codes may be added in future non-breaking releases; treat an unrecognized `code` value defensively (fall back to the HTTP status and `message`) rather than assuming this list is closed. One thing this catalogue does not cover: **infeasible plans are not an error.** Submitting a plan the engine can't fully satisfy still returns a normal `200`/`201`. The plan is accepted, and unplanned stops or constraint violations show up in the solution (`unaffectedStopIds`, `violations`) rather than as an `Error`. properties: code: type: string description: > Stable identifier for the error type. Branch your error handling on this field, not on the HTTP status alone or on this response's `description` in this spec. Several `code` values can share the same status. See the preceding table. enum: - INVALID_INPUT - ID_NOT_UNIQUE - KEYS_NOT_UNIQUE - INVALID_ID_REFERENCE - INVALID_VALUE - PRECONDITION_FAILED - NOT_IMPLEMENTED - NOT_AUTHENTICATED - NOT_ALLOWED - NOT_FOUND - INTERNAL_SERVER_ERROR example: INVALID_VALUE message: type: string description: >- Default, human-readable message. Useful for logs; not meant to be parsed. example: The field value is not valid. properties: allOf: - $ref: '#/components/schemas/ErrorProperties' required: - message - code ResourceMode: type: string description: > Whether the engine may add stops to this resource's tour beyond its `state.assignments` (`free`), or must limit the tour to those assigned entries (`fixed`). How each entry is treated within the tour is set separately, by its `status` (see `AssignmentStatus`). > **When to use.** `free` with `status: "fixed"` entries for live supervision: the entries already done are taken as given, and the engine plans further stops after them. `fixed` with `status: "assigned"` entries to check whether a given set of stops is feasible on this resource, see [Handling infeasibility](https://developers.kardinal.ai/guides/handling-infeasibility#testing-a-stop-on-a-specific-resource-with-state-assignments). > **Modelling pitfall.** `fixed` limits which stops the tour contains, not their order: with `status: "assigned"` entries, the engine still sequences them according to the plan's objectives. `free` combined with `status: "assigned"` entries isn't allowed. enum: - free - fixed default: free AssignmentStop: description: > Pins a stop onto a resource's tour. `beginTime` defaults to `arrivalTime` when omitted. If `stopId` is the id of an `AlternativesStop` alternative, `arrivalTime`, `beginTime`, and `departureTime` cannot be set: the engine still chooses and times the alternative itself. type: object properties: type: type: string description: Discriminator identifying this waypoint as a stop. enum: - stop status: allOf: - $ref: '#/components/schemas/AssignmentStatus' stopId: description: Id of the pinned stop. example: stop1 allOf: - $ref: '#/components/schemas/RegexIdValidation' arrivalTime: description: Time the resource reaches the stop. allOf: - $ref: '#/components/schemas/DateTime' beginTime: description: >- Time the resource starts serving the stop. Defaults to `arrivalTime` when omitted. allOf: - $ref: '#/components/schemas/DateTime' departureTime: description: Time the resource leaves the stop. allOf: - $ref: '#/components/schemas/DateTime' required: - type - stopId AssignmentBegin: type: object description: Pins the start of a resource's tour to a fixed departure time. properties: type: type: string description: Discriminator identifying this waypoint as the tour's begin. enum: - begin status: allOf: - $ref: '#/components/schemas/AssignmentStatus' departureTime: description: Time the resource departs. allOf: - $ref: '#/components/schemas/DateTime' required: - type - departureTime AssignmentBreak: type: object description: Pins a break onto a resource's tour. properties: type: type: string description: Discriminator identifying this waypoint as a break. enum: - break status: allOf: - $ref: '#/components/schemas/AssignmentStatus' arrivalTime: description: Time the break starts. allOf: - $ref: '#/components/schemas/DateTime' departureTime: description: Time the break ends. allOf: - $ref: '#/components/schemas/DateTime' required: - type - arrivalTime - departureTime AssignmentEnd: type: object description: Pins the end of a resource's tour to a fixed arrival time. properties: type: type: string description: Discriminator identifying this waypoint as the tour's end. enum: - end status: allOf: - $ref: '#/components/schemas/AssignmentStatus' arrivalTime: description: Time the resource arrives at the end of its tour. allOf: - $ref: '#/components/schemas/DateTime' required: - type - arrivalTime CountryCodes: type: array description: >- Countries to exclude from routing, mixing any combination of standard names, Alpha-2 codes, and Alpha-3 codes. items: allOf: - $ref: '#/components/schemas/CountryCode' example: - Switzerland - BE - ITA ShippedHazardousGood: type: string description: > ADR hazard class of a good carried by the vehicle, used to respect roads restricted to that class of hazardous goods. - explosive: Substances or articles liable to explode. - gas: Compressed, liquefied, or dissolved gases. - flammable: Flammable liquids. - combustible: Flammable solids, or solids liable to spontaneous combustion. - organic: Organic peroxides. - poison: Toxic substances. - radioactive: Radioactive materials. - corrosive: Corrosive substances. - poisonousInhalation: Substances toxic by inhalation. - harmfulToWater: Substances harmful to the aquatic environment. - other: Any hazard class not covered by the preceding values. enum: - explosive - gas - flammable - combustible - organic - poison - radioactive - corrosive - poisonousInhalation - harmfulToWater - other TunnelCategory: type: string enum: - B - C - D - E description: > ADR tunnel restriction category to route around, from `B` (least restrictive) to `E` (most restrictive). - B: Restricted for goods liable to a very large explosion. - C: Restricted for goods liable to a very large explosion, a large explosion, or a large toxic release. - D: Restricted for goods liable to a very large explosion, a large explosion, a large toxic release, or a fire. - E: Restricted for all dangerous goods, except those exempted from tunnel restrictions altogether. TimeWindowBreak: type: object description: > A required break of a given duration in a given time window, triggered by a fixed clock time. Acts like a `workingTimeWindow` plus `maxWorkingDuration` pair scoped to the break itself. properties: type: description: Discriminator identifying this break as `timeWindowBreak`. type: string enum: - timeWindowBreak duration: allOf: - $ref: '#/components/schemas/Duration' timeWindow: allOf: - $ref: '#/components/schemas/TimeWindow' example: begin: '2026-03-17T12:00:00+01:00' end: '2026-03-17T13:00:00+01:00' required: - type - duration - timeWindow TravelDurationSlidingBreak: type: object description: > Limitation rule on maximum cumulative driving time without any break. Triggered by cumulative driving time (`maxInterBreakDuration`), requiring a break of at least `minBreakDuration`. properties: type: description: >- Discriminator identifying this break as `travelDurationSlidingBreak`. type: string enum: - travelDurationSlidingBreak minBreakDuration: allOf: - $ref: '#/components/schemas/Duration' maxInterBreakDuration: allOf: - $ref: '#/components/schemas/Duration' required: - type - minBreakDuration - maxInterBreakDuration WorkingDurationSlidingBreak: type: object description: > Limitation rule on maximum cumulative working time without any break. Triggered by cumulative working time (`maxInterBreakDuration`), requiring a break of at least `minBreakDuration`. properties: type: description: >- Discriminator identifying this break as `workingDurationSlidingBreak`. type: string enum: - workingDurationSlidingBreak minBreakDuration: allOf: - $ref: '#/components/schemas/Duration' maxInterBreakDuration: allOf: - $ref: '#/components/schemas/Duration' required: - type - minBreakDuration - maxInterBreakDuration SingleStop: type: object description: > Only `id` and `position` are required. See `AlternativesStop` for a stop composed of several candidate `SingleStop` options instead of a single fixed one. properties: type: description: > Always set this explicitly (`"type": "single"`), even though it defaults and a bare stop object is accepted as-is: a discriminated-union validator re-parsing your own payload (for example a typed SDK confirming it round-trips) needs the tag present in the data itself to pick the right variant, and rejects an object missing it even when the field has a documented default. type: string enum: - single default: single id: description: Single stop ids must be unique within a plan. example: stop1 allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: allOf: - $ref: '#/components/schemas/Properties' tags: description: prefix:suffix best practice, not forced. type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - access:parking33 - capa:bat22 - setup:france position: allOf: - $ref: '#/components/schemas/Position' kind: allOf: - $ref: '#/components/schemas/StopKind' operationDuration: description: > Time spent at the stop, in ISO 8601 duration format. > **Modelling pitfall.** No built-in formula computes this. It is a plain duration computed upstream from business data, for example a fixed per-stop time plus a variable component for quantity delivered. allOf: - $ref: '#/components/schemas/Duration' example: PT10M capacities: description: >- Capacities consumed or released at this stop. See the `Capacities` schema. allOf: - $ref: '#/components/schemas/Capacities' authorizedTimeWindows: description: > One or more hard time windows for the stop. Outside all of them, the stop cannot be planned at all. Accepts an array, so more than one disjoint hard window is native, for example a site open mornings and again in the evening; the stop is feasible if reachable in any one of them. Modelling an acceptable-if-late window as a hard one fails silently: the stop is simply dropped rather than delivered late. > **Modelling pitfall.** A contractual delivery window is not automatically a hard one. Ask what should happen if the fleet cannot hit it: if a late visit is acceptable, use `preferredTimeWindows` instead. > **Modelling pitfall.** `begin`/`end` bound the resource's *arrival* at the stop, not when it finishes: the stop can complete up to `operationDuration` after `end`. To express "must be done and gone by 15:00", subtract `operationDuration` from `end` yourself (for a 15-minute operation, set `end` to `"...T14:45:00"`); the API does not do this for you. type: array uniqueItems: true items: allOf: - $ref: '#/components/schemas/TaggedTimeWindow' example: - begin: '2026-03-17T08:00:00+01:00' end: '2026-03-17T12:00:00+01:00' preferredTimeWindows: description: > One or more soft time windows for the stop, reachable outside them at the cost of the `minimizeDelay` objective rather than being dropped. type: array uniqueItems: true items: allOf: - $ref: '#/components/schemas/TaggedTimeWindow' example: - begin: '2026-03-17T09:00:00+01:00' end: '2026-03-17T11:00:00+01:00' required: - id - position AlternativesStop: type: object description: A stop composed of different alternative single stops. properties: id: description: Alternatives-group ids must be unique within a plan. example: altStop1 allOf: - $ref: '#/components/schemas/RegexIdValidation' type: description: Discriminator identifying this stop as an `alternatives` group. type: string enum: - alternatives alternatives: description: Candidate single stops, of which the engine picks at most one. type: array items: allOf: - $ref: '#/components/schemas/SingleStop' required: - id - type - alternatives StopTagPrecedencePair: type: object description: A pair of precedence stop tags. properties: previous: type: string description: Stop tag that must be visited before any stop tagged `next`. example: sector1 allOf: - $ref: '#/components/schemas/RegexIdValidation' next: type: string description: >- Stop tag that the engine tries to visit only after every stop tagged `previous`. example: sector2 allOf: - $ref: '#/components/schemas/RegexIdValidation' required: - previous - next OptimizationDirection: type: string description: >- Whether a `CustomObjective`'s cost should be driven down (`minimize`) or up (`maximize`). enum: - minimize - maximize ErrorProperties: type: object description: > Optional extra context for the error, when the API provides any. The exact keys returned in `properties` for a given `code` (for example, which field name or invalid value is included in an `INVALID_VALUE` or `INVALID_ID_REFERENCE` error) are not yet documented per `code`. Treat any `properties` content as informational and not stable. additionalProperties: type: string AssignmentStatus: type: string description: > How an entry in `state.assignments` is treated: taken as given, with its position in the sequence and its pinned times left unchallenged (`fixed`), or only assigned to this resource, with the engine sequencing it according to the plan's objectives (`assigned`). enum: - fixed - assigned default: fixed CountryCode: type: string description: A country's standard name, Alpha-2 code, or Alpha-3 code. example: Switzerland StopKind: type: string description: > Generic operation label from the resource's own point of view. It sets how the stop's `capacities` affect the resource's load: added for `pickup`, deducted for `delivery`, ignored for `acknowledgement` (an intervention with no cargo exchange). > **Modelling pitfall.** A negative quantity reverses the effect: a `delivery` of `-100` has the same effect as a `pickup` of `100`. A `delivery` whose order has no `pickup` is assumed loaded at departure. enum: - pickup - delivery - acknowledgement default: delivery TaggedTimeWindow: type: object description: > `TimeWindow` plus an optional `resourceTags` array, used for `authorizedTimeWindows` / `preferredTimeWindows` on a stop. When `resourceTags` is set, that window only applies to resources carrying a matching tag (for example an early slot reserved for a certified subcontractor); resources without the tag only see the untagged windows. properties: begin: description: Start of the window. allOf: - $ref: '#/components/schemas/DateTime' end: description: End of the window. allOf: - $ref: '#/components/schemas/DateTime' resourceTags: type: array description: >- Resource tags the window is restricted to. Omit to apply the window to every resource regardless of tag. items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB required: - begin - end responses: BadRequest: description: > The server could not understand the request due to invalid content (bad syntax, bad format, bad values, etc). Several distinct business `code` values are returned under this same `400` status. Branch your error handling on `code`, not on this description. See the examples below and the `Error` schema for the full catalogue. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' examples: invalidInput: summary: INVALID_INPUT value: errors: - code: INVALID_INPUT message: The payload cannot be parsed. idNotUnique: summary: ID_NOT_UNIQUE value: errors: - code: ID_NOT_UNIQUE message: >- The payload contains a collection with an id repeated multiple times. keysNotUnique: summary: KEYS_NOT_UNIQUE value: errors: - code: KEYS_NOT_UNIQUE message: >- The payload contains a collection with the keys repeated multiple times. invalidIdReference: summary: INVALID_ID_REFERENCE value: errors: - code: INVALID_ID_REFERENCE message: The id reference contains an id that does not exist. invalidValue: summary: INVALID_VALUE value: errors: - code: INVALID_VALUE message: The field value is not valid. preconditionFailed: summary: PRECONDITION_FAILED value: errors: - code: PRECONDITION_FAILED message: A precondition failed. notImplemented: summary: NOT_IMPLEMENTED value: errors: - code: NOT_IMPLEMENTED message: Not yet implemented. NotAuthenticated: description: > The caller is not authenticated (`code: NOT_AUTHENTICATED`): no access token was sent, or it's missing, malformed, or expired. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' examples: notAuthenticated: summary: NOT_AUTHENTICATED value: errors: - code: NOT_AUTHENTICATED message: The caller is not authenticated. Forbidden: description: > The caller is not allowed to perform this action (`code: NOT_ALLOWED`): for a builder account, this currently always means that an agency limit was reached, whether an optimization quota, a plan size limit, or insufficient credits. `properties.details` states which one. See [Limits and quotas](https://developers.kardinal.ai/reference/limits-and-quotas). content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' examples: dailyQuotaExceeded: summary: NOT_ALLOWED — daily optimization quota reached value: agencyId: BLD1234567_sandbox planId: f7ee9aa5-36e5-4ce5-a978-8d69892f7831 errors: - code: NOT_ALLOWED message: The requested action is not allowed. properties: details: >- The maximum number of optimizations per day (1500) has been reached for agency BLD1234567_sandbox insufficientCredits: summary: NOT_ALLOWED — insufficient credits value: agencyId: BLD1234567_production planId: f7ee9aa5-36e5-4ce5-a978-8d69892f7831 errors: - code: NOT_ALLOWED message: The requested action is not allowed. properties: details: Insufficient credits remaining: '17' agencyQuotaConfigViolation: summary: NOT_ALLOWED — plan size limit exceeded value: agencyId: BLD1234567_sandbox planId: f7ee9aa5-36e5-4ce5-a978-8d69892f7831 errors: - code: INVALID_VALUE message: The field value is not valid. properties: details: >- The plan's number of resources (251) is greater than the allowed value (250) for agency BLD1234567_sandbox path: resources - code: NOT_ALLOWED message: The requested action is not allowed. properties: details: >- The resulting plan violates the quotas configuration of the agency InternalServerError: description: > An internal server error has occurred (`code: INTERNAL_SERVER_ERROR`): an unexpected server-side failure, unrelated to the request's content. If this persists, contact support with the request's timestamp. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' examples: internalServerError: summary: INTERNAL_SERVER_ERROR value: errors: - code: INTERNAL_SERVER_ERROR message: >- The server encountered an unexpected condition that prevented it from fulfilling the request. securitySchemes: access_token: type: http scheme: bearer bearerFormat: JWT description: > JWT bearer token, sent as `Authorization: Bearer `. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.