Kardinal Core API

openapi: 3.2.0
info:
  title: Kardinal ARO Core API
  version: 2.55.0
  description: This document specifies the REST API of Kardinal ARO v2.
  contact:
    url: https://kardinal.ai/
    email: contact@kardinal.ai
servers:
- url: /api/v2
security:
- access_token: []
tags:
- name: Core
paths:
  /login:
    post:
      summary: Login (returns an OTP token if MFA is configured for the user)
      operationId: postLogin
      tags:
      - Core
      security: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
      responses:
        '200':
          description: The login succeeded.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EnvelopedLoginOTPOutput'
                - $ref: '#/components/schemas/EnvelopedLoginGDPROutput'
                - $ref: '#/components/schemas/EnvelopedLoginMFAOutput'
                - $ref: '#/components/schemas/EnvelopedLoginAccessOutput'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /login/otp:
    post:
      summary: Confirm login with OTP
      operationId: postLoginOTP
      tags:
      - Core
      security:
      - otp_token: []
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/LoginOTPInput'
              - $ref: '#/components/schemas/LoginBackupCodeInput'
      responses:
        '200':
          description: The login succeeded.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EnvelopedLoginGDPROutput'
                - $ref: '#/components/schemas/EnvelopedLoginAccessOutput'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agencies/{agencyId}/plans/{planId}:
    parameters:
    - $ref: '#/components/parameters/agencyId'
    - $ref: '#/components/parameters/planId'
    put:
      summary: Create or update a plan
      operationId: putPlan
      tags:
      - Core
      parameters:
      - $ref: '#/components/parameters/force'
      requestBody:
        description: The Plan to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Plan'
      responses:
        '200':
          description: Plan response updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedPlan'
        '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/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /agencies/{agencyId}/plans/{planId}/solution:
    parameters:
    - $ref: '#/components/parameters/agencyId'
    - $ref: '#/components/parameters/planId'
    get:
      summary: Retrieve a plan solution
      operationId: getPlanSolution
      tags:
      - Core
      responses:
        '200':
          description: Solution response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedSolution'
        '401':
          $ref: '#/components/responses/NotAuthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    WayPointBegin:
      type: object
      properties:
        type:
          type: string
          enum:
          - begin
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        position:
          $ref: '#/components/schemas/Position'
        status:
          example: fixed
          allOf:
          - $ref: '#/components/schemas/WayPointStatus'
        departureTime:
          $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: List of the Waypoint's violations.
        fromPrevious:
          $ref: '#/components/schemas/FromPrevious'
      required:
      - type
      - position
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    LoginOTPOutput:
      type: object
      properties:
        otpToken:
          type: string
          description: A JWT token with scope 'otp' valid for 10 minutes.
          example: eyJhbGciOiJFZERTQSJ9.eyJhdW...QwOJAQ
        preferredType:
          $ref: '#/components/schemas/OTPType'
        availableTypes:
          description: The list of OTP types which have been configured by the actor in his MFA configuration
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/OTPType'
          example:
          - email
          - sms
          - totp
        email:
          $ref: '#/components/schemas/ObfuscatedEmail'
        phoneNumber:
          $ref: '#/components/schemas/ObfuscatedPhoneNumber'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    CountryCodes:
      type: array
      items:
        $ref: '#/components/schemas/CountryCode'
      example:
      - Switzerland
      - BE
      - ITA
    GDPRToken:
      type: string
      description: A JSON Web Token with scope 'gdpr', to be used to approve a GDPR policy, valid for 1 hour.
      example: eyJhbGciOiJFZERTQSJ9.eyJhdW...cMp9DA
    EnvelopedLoginMFAOutput:
      type: object
      description: An object containing a 'mfa' JSON Web Token, returned by a successful login of a user which needs to setup MFA authentication.
      properties:
        item:
          type: object
          properties:
            mfaToken:
              $ref: '#/components/schemas/MFAToken'
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        access_token:
          allOf:
          - deprecated: true
          - $ref: '#/components/schemas/MFAToken'
    Password:
      type: string
      format: password
      description: "A user password must contain at least:\n- 1 number,\n- 1 uppercase letter,\n- 1 lowercase letter,\n- 1 special character amongst the following:\n  !\"#$%&'()*+,-./:;<=>?@[]^_`{|}~\n- 12 characters.\nAnd it must not exceed 72 bytes.\n"
      allOf:
      - type: string
        pattern: .*[0-9]{1}
      - type: string
        pattern: .*[A-Z]{1}
      - type: string
        pattern: .*[a-z]{1}
      - type: string
        pattern: .*[!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]{1}
      - type: string
        pattern: ^.{12,72}$
    OrderViolation:
      type: object
      description: Violation of a order's stops constraint.
      properties:
        type:
          type: string
          enum:
          - order
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        expectedOrderedStopIds:
          description: The stop ids in the expected order.
          type: array
          items:
            type: string
            allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        missedStopIds:
          description: The stop ids missing from the tour.
          type: array
          items:
            type: string
            allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        badlyOrderedStopIds:
          description: The stop ids badly ordered in the tour.
          type: array
          items:
            type: string
            allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
      required:
      - type
      - expectedOrderedStopIds
    MaxInterStopDurationViolation:
      type: object
      description: Violation of a resource's MaxInterStopDuration constraint.
      properties:
        type:
          type: string
          enum:
          - maxInterStopDuration
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        wayPointIndex:
          type: integer
          description: The idx of the waypoint the violation applies to.
          example: 0
        maxInterStopDuration:
          description: The expected maximum inter-stop duration.
          allOf:
          - $ref: '#/components/schemas/Duration'
        exceededDuration:
          description: The inter-stop duration that exceeds the maximum duration.
          allOf:
          - $ref: '#/components/schemas/Duration'
      required:
      - type
      - maxInterStopDuration
      - exceededDuration
    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
    EnvelopedErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    AdditionalConstraintCapacities:
      type: object
      description: This constraint is valid if all the capacities are satisfied.
      properties:
        type:
          type: string
          enum:
          - capacities
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        name:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        capacities:
          $ref: '#/components/schemas/Capacities'
        resourceTag:
          type: string
          allOf:
          - $ref: '#/components/schemas/RegexIdValidation'
      required:
      - type
      - capacities
      - resourceTag
    User:
      type: object
      description: A user is a person who can use Platform's services.
      properties:
        id:
          type: string
          format: uuid
          description: Kardinal's unique identifier.
          readOnly: true
          example: 483fad31-415d-4d9e-8edd-c8f936e71520
        username:
          $ref: '#/components/schemas/Username'
        type:
          $ref: '#/components/schemas/UserType'
        password:
          writeOnly: true
          description: The user's password.
          allOf:
          - $ref: '#/components/schemas/Password'
        role:
          $ref: '#/components/schemas/Role'
        firstname:
          type:
          - string
          - 'null'
          description: The user's first name.
          example: Martin
        lastname:
          type:
          - string
          - 'null'
          description: The user's last name.
          example: DUPONT
        level:
          $ref: '#/components/schemas/Level'
        countries:
          description: The countries whose data the user is allowed to see.
          allOf:
          - $ref: '#/components/schemas/CountryIds'
        regions:
          description: The regions whose data the user is allowed to see.
          allOf:
          - $ref: '#/components/schemas/RegionIds'
        agencies:
          description: The agencies whose data the user is allowed to see.
          allOf:
          - $ref: '#/components/schemas/AgencyIds'
        active:
          description: Represents whether the user is enabled or disabled internally.
          example: true
          type: boolean
        status:
          $ref: '#/components/schemas/UserStatus'
        lastLoginAt:
          description: Represents the last login date of the user.
          allOf:
          - $ref: '#/components/schemas/DateTime'
        createdAt:
          description: The user's creation date.
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/DateTime'
        updatedAt:
          description: The user's last update date.
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/DateTime'
        clientId:
          description: 'The id of the client whom the user is linked to.

            It can be empty for a user which level is greater than ''owner''.


            When creating a new user, this id can be left empty if:

            - the caller has the level ''region'' or ''country'' or ''owner'': in this case, the clientId of the new user is inherited from the clientId of the caller,

            - the new user has a level greater than ''owner''.

            '
          allOf:
          - $ref: '#/components/schemas/ClientId'
        gdprInfo:
          type: object
          properties:
            version:
              type: string
            approvedAt:
              $ref: '#/components/schemas/DateTime'
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        managedClientsIds:
          type: array
          description: 'For an ''admin'' user only: the ids of the clients which are managed by this user.'
          items:
            $ref: '#/components/schemas/ClientId'
      required:
      - username
    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
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        name:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        resourceTags:
          type: array
          items:
            type: string
            allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
          example:
          - subcontractorA
          - subcontractorB
        maxGroupsByStopTag:
          $ref: '#/components/schemas/MaxGroupsByStopTag'
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
      required:
      - type
      - maxGroupsByStopTag
    AuthorizedTimeWindowViolation:
      type: object
      description: Violation of a stop's TimeWindow constraint.
      properties:
        type:
          type: string
          enum:
          - authorizedTimeWindow
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        wayPointIndex:
          type: integer
          description: The idx of the waypoint the violation applies to.
          example: 0
        forbiddenWindow:
          description: The violated forbidden window.
          allOf:
          - $ref: '#/components/schemas/TimeWindow'
        actualTime:
          description: The time at which the waypoint is actually executed.
          allOf:
          - $ref: '#/components/schemas/DateTime'
      required:
      - type
      - forbiddenWindow
      - actualTime
    RegexIdValidation:
      type: string
      description: 'At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".'
      pattern: ^[a-zA-Z0-9-._~:@!$,]+$
    ForbiddenAssignmentViolation:
      type: object
      description: Violation of a ForbiddenAssignment constraint.
      properties:
        type:
          type: string
          enum:
          - forbiddenAssignment
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        wayPointIndex:
          type: integer
          description: The idx of the waypoint the violation applies to.
          example: 0
        forbiddenAssignments:
          type: array
          items:
            $ref: '#/components/schemas/ForbiddenAssignment'
          description: The list of forbidden assignments that are violated with the waypoint assigned to the resource.
      required:
      - type
    Properties:
      type: object
      additionalProperties:
        type: string
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    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
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    WayPointStop:
      type: object
      properties:
        type:
          type: string
          enum:
          - stop
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        stopId:
          type: string
          allOf:
          - $ref: '#/components/schemas/RegexIdValidation'
        position:
          $ref: '#/components/schemas/Position'
        status:
          example: optimized
          allOf:
          - $ref: '#/components/schemas/WayPointStatus'
        stopProperties:
          $ref: '#/components/schemas/Properties'
        orderProperties:
          $ref: '#/components/schemas/Properties'
        filledCapacitiesAfterStop:
          $ref: '#/components/schemas/Capacities'
        delay:
          description: Delay related to the stop's preferred time windows.
          allOf:
          - $ref: '#/components/schemas/Duration'
        arrivalTime:
          $ref: '#/components/schemas/DateTime'
        beginTime:
          $ref: '#/components/schemas/DateTime'
        departureTime:
          $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: List of the Waypoint's violations.
        fromPrevious:
          $ref: '#/components/schemas/FromPrevious'
        stopKind:
          $ref: '#/components/schemas/StopKind'
      required:
      - type
      - position
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    OTPValue:
      type: string
      description: A 6-digits OTP code.
      example: '403852'
    AdditionalConstraintAtLeastOneConstraint:
      type: object
      description: If one of the constraint is valid, then the tour is valid.
      properties:
        type:
          type: string
          enum:
          - atLeastOneConstraint
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        name:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        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'
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
      required:
      - type
      - constraints
    SolutionObjective:
      type: object
      properties:
        name:
          type: string
          allOf:
          - $ref: '#/components/schemas/RegexIdValidation'
        priority:
          type: integer
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        direction:
          $ref: '#/components/schemas/OptimizationDirection'
        value:
          type: number
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    TimeWindow:
      type: object
      properties:
        begin:
          $ref: '#/components/schemas/DateTime'
        end:
          $ref: '#/components/schemas/DateTime'
      required:
      - begin
      - end
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    IncompatibleStopTags:
      type: array
      description: Incompatibilities between stop tags (all elements must be different regardless of order).
      uniqueItems: true
      deprecated: true
      items:
        $ref: '#/components/schemas/StopTagPair'
      example:
      - - goat
        - cabbage
      - - wolf
        - goat
    AlternativesStop:
      type: object
      description: A stop composed of different alternative single stops.
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/RegexIdValidation'
        type:
          type: string
          enum:
          - alternatives
          description: Discriminator identifying this as an alternatives stop, as opposed to a single stop.
        alternatives:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/SingleStop'
          description: The list of single stops among which the algorithm must choose the best one to visit (for example choosing among multiple charging points or waste disposal sites). Using alternatives can increase optimization time.
      required:
      - type
      - alternatives
    Username:
      type: string
      description: The username is used for login, it is unique for each user, it can be either an email (for clients) or a regular username (for Kardinal's internal users).
      example: martin.dupont@kardinal.ai
      oneOf:
      - $ref: '#/components/schemas/RegexNotEmpty'
      - $ref: '#/components/schemas/Email'
    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'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Role:
      type: string
      description: The user's role.
      enum:
      - analyst
      - expert
      - super
      default: analyst
      example: expert
    CountryIds:
      type: array
      description: A list of country identifiers.
      items:
        $ref: '#/components/schemas/CountryId'
      example:
      - LND_France
      - LND_Belgique
    Plan:
      type: object
      description: A plan for a date and agency, with resource and orders associated.
      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'
          description: The plan's processing status across the optimization pipeline (waiting room, creation, optimization, and traffic-waiting stages), each tracking which plan version is currently waiting and currently running. Poll this field to know when a new solution is ready instead of relying on a push/webhook mechanism. See PlanStatus for the full breakdown of each stage.
        state:
          allOf:
          - $ref: '#/components/schemas/PlanState'
        properties:
          allOf:
          - $ref: '#/components/schemas/Properties'
          description: Free-form key-value pairs (strings only) with no impact on optimization. Used to carry integration-specific information (for example an internal reference) that is returned unchanged in the plan and its solution. Can also be set on resources, orders, and stops.
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
          description: The list of resources (vehicle/driver pairs) available to fulfill the plan's orders.
        nbResources:
          type: number
          format: integer
          minimum: 0
          readOnly: true
          description: The number of resources in the plan.
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: The list of orders (sequences of stops) to be planned across the available resources.
        nbOrders:
          type: number
          format: integer
          minimum: 0
          readOnly: true
          description: The number of orders in the plan.
        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'
        forbiddenAssignments:
          type: array
          uniqueItems: true
          deprecated: true
          items:
            $ref: '#/components/schemas/ForbiddenAssignment'
        incompatibleStopTags:
          allOf:
          - $ref: '#/components/schemas/IncompatibleStopTags'
        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'
          description: A list of advanced constraints that go beyond what the standard modeling objects (resources, orders, stops) can express, each identified by a type (for example atLeastOneValidCapacity, forbiddenAssignment, incompatibleStopTags, atLeastOneConstraint, capacities, maxStopTagGroups, or removalStrategy). See the constraints catalog for the full list and their parameters.
        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'
          description: Defines an additional duration incurred when a resource transitions from a stop tagged fromStopTag to a stop tagged toStopTag (for example customs crossings between countries, or cleaning required between incompatible cargo types), identified by the "setup:" tag convention.
        objectives:
          allOf:
          - $ref: '#/components/schemas/PlanObjectives'
          description: 'The ordered list of optimization objectives, processed lexicographically: the algorithm prioritizes improving higher-ranked objectives before lower-ranked ones, so the order should reflect business priorities. Defaults to a sequence that works well for most cases. See ObjectivesEnum for the available objectives.'
        maxOptimizationDuration:
          allOf:
          - $ref: '#/components/schemas/Duration'
        tz:
          $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
        updatedAt:
          description: The plan's last update datetime.
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/DateTime'
        updatedBy:
          type:
          - string
          - 'null'
          description: The username of the user who last updated this plan
          readOnly: true
        archivedAt:
          description: 'The plan''s archiving datetime: if not null, the plan is archived.'
          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.0
              volume: 75.0
            '*':
              weight: 50.0
        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
       

# --- truncated at 32 KB (119 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kardinal/refs/heads/main/openapi/kardinal-core-api-openapi.yml