> ## 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: sending an `id` in the payload is rejected with a `400`. Use the id returned in the response to address the plan on the other endpoints. ## OpenAPI ````yaml /openapi.yaml post /plans openapi: 3.0.3 info: title: Kardinal Builder API version: 1.0.0 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`. contact: url: https://kardinal.ai/ email: contact@kardinal.ai servers: - url: /api/v2 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 create, retrieve, update and delete webhooks on a plan. paths: /plans: post: tags: - Plan summary: Create a plan description: > The plan id is generated by the service: sending an `id` in the payload is rejected with a `400`. Use the id returned in the response to address the plan on the other endpoints. operationId: postPlan requestBody: description: The plan to create. content: application/json: schema: $ref: '#/components/schemas/Plan' responses: '201': description: Plan response created. content: application/json: schema: $ref: '#/components/schemas/EnvelopedPlan' '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, ... properties: id: $ref: '#/components/schemas/PlanId' agencyId: $ref: '#/components/schemas/AgencyId' version: $ref: '#/components/schemas/PlanVersion' running: type: boolean description: To know if the plan is running. readOnly: true status: allOf: - $ref: '#/components/schemas/PlanStatus' state: allOf: - $ref: '#/components/schemas/PlanState' properties: allOf: - $ref: '#/components/schemas/Properties' resources: type: array items: $ref: '#/components/schemas/Resource' nbResources: type: integer minimum: 0 readOnly: true orders: type: array items: $ref: '#/components/schemas/Order' nbOrders: type: integer 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: $ref: '#/components/schemas/AdditionalOperationDuration' operationDurationPoliciesByResourceTag: type: object description: Policies to remove the operation durations, by resource tag. additionalProperties: type: array items: $ref: '#/components/schemas/OperationDurationPolicy' additionalConstraints: 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' globalConstraints: type: array description: List of global constraints to be satisfied by the returned solution. items: oneOf: - $ref: '#/components/schemas/GlobalConstraintMaxCumulatedCost' accessDurationsByStopTag: type: object description: >- Access durations is an additional duration before the beginning of a group of stops with the same stop tag. additionalProperties: allOf: - $ref: '#/components/schemas/Duration' example: access:parking33: PT5M overlappingCapacitiesByStopTag: type: object description: >- This field allows users to define a limit in the number of resources that are simultaneously present at stops sharing the same stop tag. additionalProperties: type: integer example: capa:bat22: 3 setupDurations: type: array items: $ref: '#/components/schemas/SetupDuration' objectives: allOf: - $ref: '#/components/schemas/PlanObjectives' maxOptimizationDuration: allOf: - $ref: '#/components/schemas/Duration' tz: $ref: '#/components/schemas/TimeZone' createdAt: description: The plan's creation datetime. nullable: false readOnly: true allOf: - $ref: '#/components/schemas/DateTime' createdBy: type: string description: The username of the user who created this plan nullable: false readOnly: true updatedAt: description: The plan's last update datetime. nullable: true readOnly: true allOf: - $ref: '#/components/schemas/DateTime' updatedBy: type: string description: The username of the user who last updated this plan nullable: true readOnly: true archivedAt: description: 'The plan''s archiving datetime: if not null, the plan is archived.' nullable: true readOnly: true example: null allOf: - $ref: '#/components/schemas/DateTime' lateDeparture: description: True if lateDeparture is requested for Resources, false otherwise. type: boolean default: false sharedCapacities: description: >- True if sharedCapacities is requested for Resources, false otherwise. It enables resources to share capacities between stops of different orders. 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" (kilometers traveled 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: $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: $ref: '#/components/schemas/Cost' example: resTag2: km: costCoeff: 0.55 costPerCapacityPerTravelledKm: weight: costCoeff: 0.2 required: - resources EnvelopedPlan: type: object properties: item: $ref: '#/components/schemas/Plan' agencyId: $ref: '#/components/schemas/AgencyId' planId: $ref: '#/components/schemas/PlanId' planVersion: $ref: '#/components/schemas/PlanVersion' PlanId: description: The plan id. readOnly: true example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016 allOf: - $ref: '#/components/schemas/UUID' AgencyId: type: string description: The agency id. 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 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 in order 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 canceled. - deleted: The plan was deleted and awaiting optimizations were canceled. - 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 additionalProperties: type: string Resource: type: object properties: id: description: Resource ids must be unique within a plan. allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: $ref: '#/components/schemas/Properties' state: allOf: - $ref: '#/components/schemas/State' cost: 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 (e.g. `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: 0 by default, can be negative. type: integer default: 0 skills: type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - forklift - truck preferredStopTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - access:parking33 - capa:bat22 - setup:france tags: type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - trailer vehicleProfile: 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' capacities: allOf: - $ref: '#/components/schemas/Capacities' departure: allOf: - $ref: '#/components/schemas/Position' arrival: oneOf: - $ref: '#/components/schemas/Position' - $ref: '#/components/schemas/AtFirstPositionArrival' workingTimeWindow: allOf: - $ref: '#/components/schemas/TimeWindow' maxWorkingDuration: allOf: - $ref: '#/components/schemas/Duration' maxDistanceInKm: type: number maxInterStopDistanceInKm: description: | Maximum distance, in km, between two consecutive stops on a tour. Accepts either: - a scalar value — applied uniformly to every travel of the tour; - a structured object with independent bounds per segment (`firstTravel`, `interStop`, `lastTravel`); an absent key means no constraint on that segment. oneOf: - type: number description: Uniform bound, in km, applied to every travel of the tour. example: 50 - $ref: '#/components/schemas/MaxInterStopDistanceInKmBounds' maxInterStopDuration: description: | Maximum duration between two consecutive stops on a tour. Accepts either: - a scalar value — applied uniformly to every travel of the tour; - a structured object with independent bounds per segment (`firstTravel`, `interStop`, `lastTravel`); an absent key means no constraint on that segment. oneOf: - $ref: '#/components/schemas/Duration' - $ref: '#/components/schemas/MaxInterStopDurationBounds' breaks: type: array items: $ref: '#/components/schemas/Break' operationDurationPolicies: type: array items: $ref: '#/components/schemas/OperationDurationPolicy' travelTimeCoefficient: 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" (kilometers traveled 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: $ref: '#/components/schemas/AvoidEarlyLoading' required: - id - vehicleProfile - workingTimeWindow Order: type: object properties: id: description: Order ids must be unique within a plan. allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: $ref: '#/components/schemas/Properties' priority: description: 0 by default, can be negative. type: integer default: 0 optional: type: boolean requiredSkills: type: array uniqueItems: true items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - forklift - truck stops: type: array uniqueItems: true items: $ref: '#/components/schemas/Stop' successiveStops: type: boolean maxStopSpan: 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: $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 enum: - withoutFirstOperationDuration - withoutOperationDurations stopTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - access:parking33 - capa:bat22 - setup:france required: - policy AdditionalConstraintAtLeastOneValidCapacity: type: object description: >- If the tour has not, at each stop, one of its capacities lower than or equal to the link limit, then the tour is invalid. properties: type: type: string enum: - atLeastOneValidCapacity name: type: string capacities: $ref: '#/components/schemas/Capacities' resourceTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB required: - type - capacities AdditionalConstraintForbiddenAssignment: type: object description: Forbidden assignment by stop tag and resource tag. properties: type: type: string enum: - forbiddenAssignment name: type: string 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: Incompatibility between stop tags. properties: type: type: string enum: - incompatibleStopTags name: type: string stopTags: $ref: '#/components/schemas/StopTagPair' resourceTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB required: - type - stopTags AdditionalConstraintAtLeastOneConstraint: type: object description: If one of the constraint is valid, then the tour is valid. properties: type: type: string enum: - atLeastOneConstraint name: type: string constraints: 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' required: - type - constraints AdditionalConstraintCapacities: type: object description: This constraint is valid if all the capacities are satisfied. properties: type: type: string enum: - capacities name: type: string capacities: $ref: '#/components/schemas/Capacities' resourceTag: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' required: - type - capacities - resourceTag AdditionalConstraintMaxStopTagGroups: type: object description: >- If the tour has stops whose stopTags constitute too many groups, then the tour is invalid. properties: type: type: string enum: - maxStopTagGroups name: type: string resourceTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB maxGroupsByStopTag: $ref: '#/components/schemas/MaxGroupsByStopTag' required: - type - maxGroupsByStopTag AdditionalConstraintRemovalStrategy: type: object description: >- If the tour does not respect the defined removal strategy, then the tour is invalid. properties: type: type: string enum: - removalStrategy name: type: string resourceTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' example: - subcontractorA - subcontractorB capacities: 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: Provide an upper bound on the cost of specified resources. properties: type: type: string enum: - maxCumulatedCost name: type: string maximum: type: number costsByResourceTag: $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 properties: fromStopTag: type: string example: setup:france allOf: - $ref: '#/components/schemas/RegexIdValidation' toStopTag: type: string example: setup:belgium allOf: - $ref: '#/components/schemas/RegexIdValidation' setupDuration: allOf: - $ref: '#/components/schemas/Duration' required: - fromStopTag - toStopTag - setupDuration PlanObjectives: type: array 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: > The time zone is a string code which identifies a region of the world in the "time zone database", also called "tz database". The tz database is a partition of the world into regions where local clocks all show the same time. This database gives the rules for time offset and daylight saving time in each region. How do we use it? In order to work with time events accurately, we usually use datetimes in the iso-8601 format, without explicit time zone. This format is quite well suported by many programming languages, and it is well suited for technical data exchange. But it is not easy to use for humans. For instance, here are three datetimes in iso-8601 format, which give the same exact moment in time: - "2025-05-22T05:43:00Z" - "2025-05-22T06:43:00+01:00" - "2025-05-22T07:43:00+02:00" For a non-technical user, it is difficult to know how to relate this to the time displayed on a watch or a clock. We improve the user experience by adding the support of local datetimes, thanks to the use of the time zone, which allows to transform a local datetime into an iso-8601 datetime: - local datetime + timezone (tz) = iso-8601 datetime For instance, here are five datetimes which all give the same exact moment in time: - "2025-05-22T05:43:00Z" - "2025-05-22T06:43:00+01:00" - "2025-05-22T07:43:00+02:00" - "2025-05-22 07:43:00" + timezone "tz": "Europe/Paris" - "2025-05-22 07:43" + timezone "tz": "Europe/Paris" Note: the last example ("2025-05-22 07:43") illustrates the support of local datetimes without seconds, which can be very practical for users. In order for local datetimes to be supported, some JSON input objects contain a "tz" time zone property. This "tz" property is used to pre-process the JSON input payload, like this: - We check if a valid timezone can be extracted from the "tz" property, - If so, we perform the following actions: - Walk through the whole JSON content to look for local datetimes, - Use the timezone to transform each local datetime into an iso-8601 datetime. Important: some objects contain a "properties" sub-object, which is a map of custom client data; the content of the "properties" sub-objects is always excluded from the time zone pre-processing. 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 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. 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 properties: workedHours: $ref: '#/components/schemas/CostFloorsAndCoeffs' km: $ref: '#/components/schemas/CostFloorsAndCoeffs' using: type: number costsByStopTag: type: object additionalProperties: $ref: '#/components/schemas/CostFloorsAndCoeffs' costsByCapacity: type: object additionalProperties: $ref: '#/components/schemas/TaggedCostFloorsAndCoeffs' costPerCapacityPerTravelledKm: type: object description: > Contribution to cost proportional to travelled distance and transported capacity. For each capacity, the contribution is `costCoeff × distance(km) × transportedCapacity`. Unit: cost per capacity unit per kilometre (e.g. €/tonne/km). Cumulable with `costPerCapacityPerTravelledHour` and with the other cost fields; the two travelled-cost maps are independent. additionalProperties: $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. For each capacity, the contribution is `costCoeff × travelDuration(h) × transportedCapacity`. Unit: cost per capacity unit per hour (e.g. €/tonne/h). The `Travelled` qualifier means travel duration only — not total working time. Cumulable with `costPerCapacityPerTravelledKm` and with the other cost fields; the two travelled-cost maps are independent. additionalProperties: $ref: '#/components/schemas/CostFloorsAndCoeffs' example: weight: costCoeff: 0.05 EnvelopedErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' 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 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, "-", ".", "_", "~", ":", "@", "!", "$", ",". pattern: ^[a-zA-Z0-9-._~:@!$,]+$ State: type: object properties: mode: $ref: '#/components/schemas/ResourceMode' assignments: type: array items: oneOf: - $ref: '#/components/schemas/AssignmentStop' - $ref: '#/components/schemas/AssignmentBegin' - $ref: '#/components/schemas/AssignmentBreak' - $ref: '#/components/schemas/AssignmentEnd' VehicleProfileFly: type: object properties: type: type: string enum: - fly kmph: type: number required: - type VehicleProfilePedestrian: type: object properties: type: type: string enum: - pedestrian avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidDirtRoad: type: boolean excludedCountries: $ref: '#/components/schemas/CountryCodes' required: - type VehicleProfileBicycle: type: object properties: type: type: string enum: - bicycle avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidTunnel: type: boolean avoidDirtRoad: type: boolean excludedCountries: $ref: '#/components/schemas/CountryCodes' required: - type VehicleProfileScooter: type: object properties: type: type: string enum: - scooter avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidCarShuttleTrain: type: boolean avoidTunnel: type: boolean avoidDirtRoad: type: boolean excludedCountries: $ref: '#/components/schemas/CountryCodes' speedCap: type: number required: - type VehicleProfileMotorbike: type: object properties: type: type: string enum: - motorbike avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidControlledAccessHighway: type: boolean avoidCarShuttleTrain: type: boolean avoidTunnel: type: boolean avoidDirtRoad: type: boolean excludedCountries: $ref: '#/components/schemas/CountryCodes' speedCap: type: number required: - type VehicleProfileCar: type: object properties: type: type: string enum: - car withTraffic: type: boolean avoidTollRoad: type: boolean avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidControlledAccessHighway: type: boolean avoidCarShuttleTrain: type: boolean avoidTunnel: type: boolean avoidDirtRoad: type: boolean avoidUTurns: type: boolean excludedCountries: $ref: '#/components/schemas/CountryCodes' speedCap: type: number required: - type VehicleProfileTruck: type: object properties: type: type: string enum: - truck grossWeight: type: number withTraffic: type: boolean avoidTollRoad: type: boolean avoidFerry: type: boolean avoidSeasonalClosure: type: boolean avoidControlledAccessHighway: type: boolean avoidCarShuttleTrain: type: boolean avoidTunnel: type: boolean avoidDirtRoad: type: boolean avoidUTurns: type: boolean shippedHazardousGoods: type: array items: $ref: '#/components/schemas/ShippedHazardousGood' example: - explosive - gas - flammable excludedCountries: $ref: '#/components/schemas/CountryCodes' height: type: number width: type: number length: type: number tunnelCategory: $ref: '#/components/schemas/TunnelCategory' speedCap: type: number required: - type Position: type: object properties: lon: type: number minimum: -180 maximum: 180 lat: 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 it's Tour first position. enum: - atFirstPosition TimeWindow: type: object properties: begin: $ref: '#/components/schemas/DateTime' end: $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 interStop: description: >- Maximum distance, in km, between two consecutive intermediate stops (excluding the first and last travels). type: number lastTravel: description: >- Maximum distance, in km, between the last stop and the resource's arrival. type: number 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: oneOf: - $ref: '#/components/schemas/TimeWindowBreak' - $ref: '#/components/schemas/TravelDurationSlidingBreak' - $ref: '#/components/schemas/WorkingDurationSlidingBreak' Stop: oneOf: - $ref: '#/components/schemas/SingleStop' - $ref: '#/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 additionalProperties: type: integer example: depot: 2 delivery: 10 RemovalStrategyType: type: string enum: - lifo default: lifo CostsByResourceTag: type: object additionalProperties: $ref: '#/components/schemas/Cost' ObjectivesEnum: type: string enum: - maximizeMandatoryStops - minimizeDelay - minimizeCosts - minimizeResources - minimizeOverOverlappingCapacitiesOnStops - maximizeOptionalStops - maximizePreferredStops - minimizeLargestTourDuration - minimizeWorkingDuration - minimizeDistance - minimizeEarlyLoadings MaximizePrecedencesObjective: type: object properties: type: type: string enum: - maximizePrecedences precedences: type: array items: allOf: - $ref: '#/components/schemas/StopTagPrecedencePair' disableGroupProximity: type: boolean description: If true, the group proximity objective will be disabled. required: - type - precedences CustomObjective: type: object properties: type: type: string enum: - custom name: type: string not: type: string pattern: >- ^(maximizeMandatoryStops|minimizeDelay|minimizeCosts|minimizeResources|minimizeOverOverlappingCapacitiesOnStops|maximizeOptionalStops|maximizePreferredStops|minimizeLargestTourDuration|minimizeWorkingDuration|minimizeDistance|minimizeEarlyLoadings)$ direction: $ref: '#/components/schemas/OptimizationDirection' costsByResourceTag: $ref: '#/components/schemas/CostsByResourceTag' required: - type - name - direction - costsByResourceTag CostFloorsAndCoeffs: type: object description: >- Cost floors and coefficients. A cost cannot be empty. An overcost cannot be set if there is no cost, and the overcostFloor must be greater than costFloor. properties: constantCost: type: number costFloor: type: number costCoeff: type: number overcostFloor: type: number overcostCoeff: type: number TaggedCostFloorsAndCoeffs: type: object allOf: - $ref: '#/components/schemas/CostFloorsAndCoeffs' properties: stopTags: type: array items: type: string allOf: - $ref: '#/components/schemas/RegexIdValidation' uniqueItems: true example: - warehouse - stop Error: type: object readOnly: true properties: code: type: string message: type: string properties: $ref: '#/components/schemas/ErrorProperties' required: - message - code ResourceMode: type: string enum: - free - fixed default: free AssignmentStop: description: >- The beginTime is set to arrivalTime if not setted. If the stopId is the id of an alternative, arrivalTime, beginTime, and departureTime cannot be set and the chosen alternative stop is optimized by the solver. type: object properties: type: type: string enum: - stop status: $ref: '#/components/schemas/AssignmentStatus' stopId: $ref: '#/components/schemas/RegexIdValidation' arrivalTime: $ref: '#/components/schemas/DateTime' beginTime: $ref: '#/components/schemas/DateTime' departureTime: $ref: '#/components/schemas/DateTime' required: - stopId AssignmentBegin: type: object properties: type: type: string enum: - begin status: $ref: '#/components/schemas/AssignmentStatus' departureTime: $ref: '#/components/schemas/DateTime' required: - type - departureTime AssignmentBreak: type: object properties: type: type: string enum: - break status: $ref: '#/components/schemas/AssignmentStatus' arrivalTime: $ref: '#/components/schemas/DateTime' departureTime: $ref: '#/components/schemas/DateTime' required: - type - arrivalTime - departureTime AssignmentEnd: type: object properties: type: type: string enum: - end status: $ref: '#/components/schemas/AssignmentStatus' arrivalTime: $ref: '#/components/schemas/DateTime' required: - type - arrivalTime CountryCodes: type: array items: $ref: '#/components/schemas/CountryCode' example: - Switzerland - BE - ITA ShippedHazardousGood: type: string enum: - explosive - gas - flammable - combustible - organic - poison - radioactive - corrosive - poisonousInhalation - harmfulToWater - other TunnelCategory: type: string enum: - B - C - D - E description: Tunnel category restriction for truck routing (ADR tunnel categories) TimeWindowBreak: type: object description: A required break of a given duration in a given time window. properties: type: type: string enum: - timeWindowBreak duration: allOf: - $ref: '#/components/schemas/Duration' timeWindow: allOf: - $ref: '#/components/schemas/TimeWindow' required: - duration - timeWindow TravelDurationSlidingBreak: type: object description: Limitation rule on max travel duration without any break. properties: type: 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 max working duration without any break. properties: type: type: string enum: - workingDurationSlidingBreak minBreakDuration: allOf: - $ref: '#/components/schemas/Duration' maxInterBreakDuration: allOf: - $ref: '#/components/schemas/Duration' required: - type - minBreakDuration - maxInterBreakDuration SingleStop: type: object properties: type: type: string enum: - single default: single id: description: Single stop ids must be unique within a plan. allOf: - $ref: '#/components/schemas/RegexIdValidation' properties: $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: $ref: '#/components/schemas/StopKind' operationDuration: allOf: - $ref: '#/components/schemas/Duration' capacities: allOf: - $ref: '#/components/schemas/Capacities' authorizedTimeWindows: type: array uniqueItems: true items: $ref: '#/components/schemas/TaggedTimeWindow' preferredTimeWindows: type: array uniqueItems: true items: $ref: '#/components/schemas/TaggedTimeWindow' required: - id - position AlternativesStop: type: object description: A stop composed of different alternative single stops. properties: id: allOf: - $ref: '#/components/schemas/RegexIdValidation' type: type: string enum: - alternatives alternatives: type: array items: allOf: - $ref: '#/components/schemas/SingleStop' required: - type - alternatives StopTagPrecedencePair: type: object description: A pair of precedence stop tags. properties: previous: type: string example: sector1 allOf: - $ref: '#/components/schemas/RegexIdValidation' next: type: string example: sector2 allOf: - $ref: '#/components/schemas/RegexIdValidation' required: - previous - next OptimizationDirection: type: string enum: - minimize - maximize ErrorProperties: type: object additionalProperties: type: string AssignmentStatus: type: string enum: - fixed - assigned default: fixed CountryCode: type: string description: A country standard name or Alpha-2 code or Alpha-3 code. StopKind: type: string enum: - pickup - delivery - acknowledgement default: delivery TaggedTimeWindow: type: object description: TimeWindow with resource tags. properties: begin: $ref: '#/components/schemas/DateTime' end: $ref: '#/components/schemas/DateTime' resourceTags: type: array 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). content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' NotAuthenticated: description: The caller is not authenticated. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' Forbidden: description: The caller is not allowed to perform this action. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' InternalServerError: description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' securitySchemes: access_token: type: http scheme: bearer bearerFormat: JWT ````