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

# Retrieve a plan solution

> Returns the current best solution for the plan. It may still improve while optimization continues — check the plan's state (`GET /plans/{planId}/state`) to know whether it has settled.




## OpenAPI

````yaml /openapi.yaml get /plans/{planId}/solution
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/{planId}/solution:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      tags:
        - Solution
      summary: Retrieve a plan solution
      description: >
        Returns the current best solution for the plan. It may still improve
        while optimization continues — check the plan's state (`GET
        /plans/{planId}/state`) to know whether it has settled.
      operationId: getPlanSolution
      responses:
        '200':
          description: Solution response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedSolution'
              examples:
                minimalPlan:
                  summary: Solution for the minimal plan example
                  value:
                    item:
                      agencyId: BLD1234567_production
                      planId: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016
                      planVersion: 1
                      timestamp: '2026-03-21T08:00:05Z'
                      unaffectedStopIds: []
                      unusedResourceIds: []
                      objectives:
                        - name: maximizeMandatoryStops
                          priority: 0
                          direction: maximize
                          value: 3
                      tours:
                        - resourceId: resource1
                          distanceInKm: 10.509
                          workingDuration: PT25M16S
                          wayPoints:
                            - type: stop
                              stopId: Station-f
                              arrivalTime: '2026-03-21T08:00:00Z'
                              stopKind: pickup
                            - type: stop
                              stopId: Balard
                              arrivalTime: '2026-03-21T08:11:04Z'
                              stopKind: pickup
                            - type: stop
                              stopId: Dauphine
                              arrivalTime: '2026-03-21T08:19:46Z'
                              stopKind: pickup
                    agencyId: BLD1234567_production
                    planId: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016
                    planVersion: 1
        '401':
          $ref: '#/components/responses/NotAuthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    planId:
      name: planId
      description: The plan UUID.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
  schemas:
    EnvelopedSolution:
      type: object
      description: >-
        A single solution wrapped with its identifying metadata, as returned by
        the solution-retrieval endpoint.
      properties:
        item:
          description: The solution itself.
          allOf:
            - $ref: '#/components/schemas/Solution'
        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'
    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
    Solution:
      type: object
      readOnly: true
      description: >
        The engine's best solution found for a plan: which tour each resource
        runs, which stops could not be placed, and the resulting objective
        values.


        > **Modelling pitfall.** An infeasible or partially served plan is not
        an error: the response is still a normal `200`/`201`. Check
        `unaffectedStopIds` and `tours[].violations` to detect an incomplete
        solution, rather than relying on the HTTP status.
      properties:
        agencyId:
          allOf:
            - $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
        planVersion:
          allOf:
            - $ref: '#/components/schemas/PlanVersion'
        timestamp:
          description: When this solution was computed.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        unaffectedStopIds:
          type: array
          description: >-
            Ids of standalone stops that could not be placed on any tour in this
            solution.
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop2
        unaffectedAlternativeIds:
          type: array
          description: >-
            Ids of individual `AlternativesStop` alternatives that were not the
            one chosen for their group.
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - altStop1
        unusedResourceIds:
          type: array
          description: Ids of resources that were not assigned any stop in this solution.
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - resource2
        objectives:
          type: array
          description: >-
            Achieved value of each objective in `Plan.objectives`, in the same
            priority order.
          items:
            allOf:
              - $ref: '#/components/schemas/SolutionObjective'
          example:
            - name: maximizeMandatoryStops
              priority: 0
              direction: maximize
              value: 232
            - name: minimizeDelay
              priority: 1
              direction: minimize
              value: 3600
            - name: minimizeResources
              priority: 2
              direction: minimize
              value: 232
            - name: maximizeOptionalStops
              priority: 3
              direction: maximize
              value: 232
            - name: minimizeLargestTourDuration
              priority: 4
              direction: minimize
              value: 1000
            - name: minimizeWorkingDuration
              priority: 5
              direction: minimize
              value: 83430
            - name: minimizeDistance
              priority: 6
              direction: minimize
              value: 88232.4
        tours:
          type: array
          description: One tour per resource that was assigned at least one stop.
          uniqueItems: true
          items:
            allOf:
              - $ref: '#/components/schemas/Tour'
        totalDelay:
          description: Total delay of the solution related to the preferred time windows.
          allOf:
            - $ref: '#/components/schemas/Duration'
        emptyDistanceInKm:
          description: >
            Total distance (in kilometres) travelled by all resources while
            "empty".
          type: number
          format: float
          example: 123.45
        CO2Emission:
          description: >
            Total CO2 emissions of the solution (sum of each tour's
            `CO2Emission`). Present only when at least one resource has a
            `CO2EmissionCalculation` (either on the resource itself or via
            `CO2EmissionCalculationByResourceTag` on the plan).
          type: number
          format: float
          example: 67890.1
        totalTollCostsByCurrency:
          description: >-
            Total toll costs of the solution, by currency code (sum of each
            tour's `tollCostsByCurrency`).
          allOf:
            - $ref: '#/components/schemas/CostsByCurrency'
        globalViolations:
          type: array
          description: >-
            Constraint violations that apply to the solution as a whole rather
            than to a single tour.
          items:
            oneOf:
              - $ref: '#/components/schemas/GlobalViolationMaxCumulatedCost'
            discriminator:
              propertyName: type
              mapping:
                maxCumulatedCost: '#/components/schemas/GlobalViolationMaxCumulatedCost'
    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
    PlanId:
      description: The plan id.
      readOnly: true
      example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016
      allOf:
        - $ref: '#/components/schemas/UUID'
    PlanVersion:
      type: integer
      description: The plan version.
      readOnly: true
      minimum: 1
      example: 42
    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.
    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'
    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-._~:@!$,]+$
    SolutionObjective:
      type: object
      description: Achieved value of one objective from `Plan.objectives`.
      properties:
        name:
          type: string
          description: >-
            Objective name, matching an `ObjectivesEnum` value or a
            `CustomObjective`'s `name`.
          example: minimizeCosts
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        priority:
          type: integer
          description: >-
            Priority level covered by this objective entry. Only set for
            `maximizeMandatoryStops`, `maximizeOptionalStops`, and
            `minimizeResources`, which the engine splits into one entry per
            `priority` value present in the plan, so the same objective can
            appear once per level.
        direction:
          description: Whether this objective's value was minimized or maximized.
          allOf:
            - $ref: '#/components/schemas/OptimizationDirection'
        value:
          type: number
          description: Achieved value of the objective for this solution.
    Tour:
      type: object
      description: >
        One resource's planned sequence of waypoints (begin, stops, breaks, end)
        in a solution, together with its aggregate costs, durations, and
        constraint violations.
      properties:
        resourceId:
          type: string
          description: Id of the resource this tour was built for.
          example: resource1
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        mode:
          description: Resource mode this tour was computed under.
          allOf:
            - $ref: '#/components/schemas/ResourceMode'
        distanceInKm:
          type: number
          description: >-
            Total distance travelled by the resource over the whole tour, in
            kilometres.
          example: 245.3
        emptyDistanceInKm:
          description: >
            Distance (in kilometres) travelled by this resource while "empty"
            (that is, with all capacities below their respective thresholds).
          type: number
          format: float
          example: 10.5
        tourCost:
          type: number
          description: >-
            Total cost of the tour, computed from the resource's `cost`
            definition (or the plan's `costsByResourceTag`/`CustomObjective`).
          example: 1234.5
        tollCostsByCurrency:
          description: Toll costs of this tour, by currency code.
          allOf:
            - $ref: '#/components/schemas/CostsByCurrency'
        CO2Emission:
          description: >
            Total CO2 emissions of this tour, based on the given definition in
            `CO2EmissionCalculation`. Present only when the resource has a
            `CO2EmissionCalculation` (either on the resource itself or via
            `CO2EmissionCalculationByResourceTag` on the plan).
          type: number
          format: float
          example: 12345.6
        totalDelay:
          description: Total delay of the tour related to the preferred time windows.
          allOf:
            - $ref: '#/components/schemas/Duration'
        travelDuration:
          description: Total time spent travelling between waypoints over the whole tour.
          allOf:
            - $ref: '#/components/schemas/Duration'
        workingDuration:
          description: >-
            Total time spent actively working (serving stops and breaks) over
            the whole tour.
          allOf:
            - $ref: '#/components/schemas/Duration'
        waitingDuration:
          description: >-
            Total time spent waiting, for example arriving before a stop's time
            window opens, over the whole tour.
          allOf:
            - $ref: '#/components/schemas/Duration'
        resourceCapacities:
          description: >-
            List of capacities and associated quantity for which the resource
            has a restriction on the quantity to be carried at each stop during
            the tour.
          allOf:
            - $ref: '#/components/schemas/Capacities'
        maxFilledCapacities:
          description: >-
            List of each capacity transported by the resource, as well as the
            maximum quantity reached for this capacity at a stop during the
            tour.
          allOf:
            - $ref: '#/components/schemas/Capacities'
        filledCapacitiesAtBegin:
          description: Capacities loaded on the resource at the start of the tour.
          allOf:
            - $ref: '#/components/schemas/Capacities'
        filledCapacitiesAtEnd:
          description: Capacities remaining on the resource at the end of the tour.
          allOf:
            - $ref: '#/components/schemas/Capacities'
        isValid:
          description: >
            Whether the tour satisfies every hard constraint on the resource.


            > **Modelling pitfall.** Reflects only hard-constraint satisfaction.
            A tour can have `isValid: true` while still carrying soft-constraint
            violations, such as missed preferred time windows reflected in
            `totalDelay`; check `violations` for the full picture rather than
            `isValid` alone.
          type: boolean
        violations:
          type: array
          items:
            $ref: '#/components/schemas/TourViolation'
          description: Constraint violations found on this tour.
        wayPoints:
          type: array
          description: >-
            Ordered sequence of waypoints making up the tour, from the
            resource's departure to its arrival.
          items:
            oneOf:
              - $ref: '#/components/schemas/WayPointBegin'
              - $ref: '#/components/schemas/WayPointStop'
              - $ref: '#/components/schemas/WayPointBreak'
              - $ref: '#/components/schemas/WayPointEnd'
            discriminator:
              propertyName: type
              mapping:
                begin: '#/components/schemas/WayPointBegin'
                stop: '#/components/schemas/WayPointStop'
                break: '#/components/schemas/WayPointBreak'
                end: '#/components/schemas/WayPointEnd'
        vehicleProfile:
          description: >-
            Vehicle profile actually used to compute this tour's travel times
            and distances.
          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'
    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
    CostsByCurrency:
      type: object
      description: >
        Cost ranges mapped by currency code. Each currency code is a
        three-letter string following the ISO 4217 specification (for example
        `EUR`, `CHF`). See https://en.wikipedia.org/wiki/ISO_4217 for more
        details.
      readOnly: true
      additionalProperties:
        allOf:
          - $ref: '#/components/schemas/CostRange'
      example:
        EUR:
          min: 42.15
          max: 58.6
        CHF:
          min: 13.22
          max: 13.22
    GlobalViolationMaxCumulatedCost:
      type: object
      description: Violation of a `GlobalConstraintMaxCumulatedCost` constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxCumulatedCost`.
          enum:
            - maxCumulatedCost
        name:
          type: string
          description: >-
            Name of the `GlobalConstraintMaxCumulatedCost` constraint the
            violation is linked to.
          example: fleetCostCap
        resourceIds:
          type: array
          description: >-
            Ids of the resources whose cumulated cost is included in
            `exceededCost`.
          uniqueItems: true
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - resource1
            - resource2
        maximum:
          description: The constraint's maximum allowed cumulated cost.
          type: number
          example: 1000
        exceededCost:
          type: number
          description: The cumulated cost by which `maximum` was exceeded.
          example: 150
    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
    OptimizationDirection:
      type: string
      description: >-
        Whether a `CustomObjective`'s cost should be driven down (`minimize`) or
        up (`maximize`).
      enum:
        - minimize
        - maximize
    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
    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": <max item
        size>}`) 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
    TourViolation:
      description: >
        A single constraint violation found on a tour. Branch on `type` to read
        the fields specific to that violation kind, or handle an unrecognized
        `type` generically without inspecting its other fields.
      oneOf:
        - $ref: '#/components/schemas/BeginViolation'
        - $ref: '#/components/schemas/EndViolation'
        - $ref: '#/components/schemas/SkillsViolation'
        - $ref: '#/components/schemas/ForbiddenAssignmentViolation'
        - $ref: '#/components/schemas/AuthorizedTimeWindowViolation'
        - $ref: '#/components/schemas/CapacityViolation'
        - $ref: '#/components/schemas/AtLeastOneValidCapacityViolation'
        - $ref: '#/components/schemas/SuccessiveStopsViolation'
        - $ref: '#/components/schemas/OrderViolation'
        - $ref: '#/components/schemas/MaxStopSpanViolation'
        - $ref: '#/components/schemas/WorkingTimeWindowViolation'
        - $ref: '#/components/schemas/MaxWorkingDurationViolation'
        - $ref: '#/components/schemas/MaxDistanceInKmViolation'
        - $ref: '#/components/schemas/MaxInterStopDistanceInKmViolation'
        - $ref: '#/components/schemas/MaxInterStopDurationViolation'
        - $ref: '#/components/schemas/StopIncompatibilityViolation'
        - $ref: '#/components/schemas/AtLeastOneConstraintViolation'
        - $ref: '#/components/schemas/MaxStopTagGroupsViolation'
        - $ref: '#/components/schemas/RemovalStrategyViolation'
      discriminator:
        propertyName: type
        mapping:
          begin: '#/components/schemas/BeginViolation'
          end: '#/components/schemas/EndViolation'
          skills: '#/components/schemas/SkillsViolation'
          forbiddenAssignment: '#/components/schemas/ForbiddenAssignmentViolation'
          authorizedTimeWindow: '#/components/schemas/AuthorizedTimeWindowViolation'
          capacity: '#/components/schemas/CapacityViolation'
          atLeastOneValidCapacity: '#/components/schemas/AtLeastOneValidCapacityViolation'
          successiveStops: '#/components/schemas/SuccessiveStopsViolation'
          order: '#/components/schemas/OrderViolation'
          maxStopSpan: '#/components/schemas/MaxStopSpanViolation'
          workingTimeWindow: '#/components/schemas/WorkingTimeWindowViolation'
          maxWorkingDuration: '#/components/schemas/MaxWorkingDurationViolation'
          maxDistanceInKm: '#/components/schemas/MaxDistanceInKmViolation'
          maxInterStopDistanceInKm: '#/components/schemas/MaxInterStopDistanceInKmViolation'
          maxInterStopDuration: '#/components/schemas/MaxInterStopDurationViolation'
          stopIncompatibility: '#/components/schemas/StopIncompatibilityViolation'
          atLeastOneConstraint: '#/components/schemas/AtLeastOneConstraintViolation'
          maxStopTagGroups: '#/components/schemas/MaxStopTagGroupsViolation'
          removalStrategy: '#/components/schemas/RemovalStrategyViolation'
    WayPointBegin:
      type: object
      description: The start of a tour, where the resource departs from.
      properties:
        type:
          type: string
          description: Discriminator identifying this waypoint as the tour's begin.
          enum:
            - begin
        position:
          description: Geographic position the resource departs from.
          allOf:
            - $ref: '#/components/schemas/Position'
        status:
          example: fixed
          allOf:
            - $ref: '#/components/schemas/WayPointStatus'
        departureTime:
          description: Time the resource departs.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: Constraint violations found at this waypoint.
        fromPrevious:
          allOf:
            - $ref: '#/components/schemas/FromPrevious'
      required:
        - type
        - position
    WayPointStop:
      type: object
      description: A single stop visited on a tour.
      properties:
        type:
          type: string
          description: Discriminator identifying this waypoint as a stop.
          enum:
            - stop
        stopId:
          type: string
          description: Id of the visited stop.
          example: stop1
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        position:
          description: Geographic position of the stop.
          allOf:
            - $ref: '#/components/schemas/Position'
        status:
          example: optimized
          allOf:
            - $ref: '#/components/schemas/WayPointStatus'
        stopProperties:
          description: Free-form properties carried over from the stop itself.
          allOf:
            - $ref: '#/components/schemas/Properties'
        orderProperties:
          description: >-
            Free-form properties carried over from the order this stop belongs
            to.
          allOf:
            - $ref: '#/components/schemas/Properties'
        filledCapacitiesAfterStop:
          description: Capacities loaded on the resource immediately after this stop.
          allOf:
            - $ref: '#/components/schemas/Capacities'
        delay:
          description: Delay related to the stop's preferred time windows.
          allOf:
            - $ref: '#/components/schemas/Duration'
        arrivalTime:
          description: Time the resource reaches the stop.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        beginTime:
          description: Time the resource starts serving the stop.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        departureTime:
          description: Time the resource leaves the stop.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: Constraint violations found at this waypoint.
        fromPrevious:
          allOf:
            - $ref: '#/components/schemas/FromPrevious'
        stopKind:
          description: This stop's operation label, carried over from the stop itself.
          allOf:
            - $ref: '#/components/schemas/StopKind'
      required:
        - type
        - position
    WayPointBreak:
      type: object
      description: A resource break taken during a tour.
      properties:
        type:
          type: string
          description: Discriminator identifying this waypoint as a break.
          enum:
            - break
        status:
          example: optimized
          allOf:
            - $ref: '#/components/schemas/WayPointStatus'
        arrivalTime:
          description: Time the break starts.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        departureTime:
          description: Time the break ends.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: Constraint violations found at this waypoint.
        fromPrevious:
          allOf:
            - $ref: '#/components/schemas/FromPrevious'
      required:
        - type
    WayPointEnd:
      type: object
      description: The end of a tour, where the resource finishes.
      properties:
        type:
          type: string
          description: Discriminator identifying this waypoint as the tour's end.
          enum:
            - end
        position:
          description: Geographic position the resource arrives at.
          allOf:
            - $ref: '#/components/schemas/Position'
        status:
          example: optimized
          allOf:
            - $ref: '#/components/schemas/WayPointStatus'
        arrivalTime:
          description: Time the resource arrives.
          allOf:
            - $ref: '#/components/schemas/DateTime'
        violations:
          type: array
          items:
            $ref: '#/components/schemas/WaypointViolation'
          description: Constraint violations found at this waypoint.
        fromPrevious:
          allOf:
            - $ref: '#/components/schemas/FromPrevious'
      required:
        - type
        - position
    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
    CostRange:
      type: object
      description: A range of cost values (min equals max when the cost is a fixed value).
      readOnly: true
      properties:
        min:
          type: number
          description: The minimum cost
          example: 42.15
        max:
          type: number
          description: The maximum cost
          example: 58.6
      required:
        - min
        - max
    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
    BeginViolation:
      type: object
      description: >-
        Violation of a resource's departure position constraint at the beginning
        of a tour.
      properties:
        type:
          type: string
          description: The violation's type.
          enum:
            - begin
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
      required:
        - type
    EndViolation:
      type: object
      description: >-
        Violation of a resource's arrival position constraint at the end of a
        tour.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `end`.
          enum:
            - end
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
      required:
        - type
    SkillsViolation:
      type: object
      description: >
        Violation of a Skill constraint.


        > **Modelling pitfall.** Add the missing skill to the resource, or relax
        `requiredSkills` on the order if the requirement was set too strictly.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `skills`.
          enum:
            - skills
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        lackingSkills:
          type: array
          description: >-
            The list of skills needed to do the waypoint that the resource
            lacks.
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - forklift
            - truck
      required:
        - type
    ForbiddenAssignmentViolation:
      type: object
      description: Violation of a ForbiddenAssignment constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `forbiddenAssignment`.
          enum:
            - forbiddenAssignment
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        forbiddenAssignments:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/ForbiddenAssignment'
          description: >-
            The list of forbidden assignments that are violated with the
            waypoint assigned to the resource.
      required:
        - type
    AuthorizedTimeWindowViolation:
      type: object
      description: >
        Violation of a stop's TimeWindow constraint.


        > **Modelling pitfall.** Confirm with the business whether the window is
        genuinely non-negotiable; if not, switch it to `preferredTimeWindows` so
        a late visit is tracked as `delay` instead of left unplanned. If it must
        stay hard, widen the window or free up capacity/skills elsewhere in the
        tour.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `authorizedTimeWindow`.
          enum:
            - authorizedTimeWindow
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        forbiddenWindow:
          description: >-
            The `authorizedTimeWindows` entry the stop's actual arrival falls
            outside of.
          allOf:
            - $ref: '#/components/schemas/TimeWindow'
          example:
            begin: '2026-03-17T08:00:00+01:00'
            end: '2026-03-17T12:00:00+01:00'
        actualTime:
          description: The time at which the waypoint is actually executed.
          allOf:
            - $ref: '#/components/schemas/DateTime'
      required:
        - type
        - forbiddenWindow
        - actualTime
    CapacityViolation:
      type: object
      description: >
        Violation of a resource's capacity constraint.


        > **Modelling pitfall.** Check `capacity`/`overCapacity` against the
        fleet's declared capacities: either the resource needs more capacity on
        that dimension, or the demand should be split across more resources or
        trips (see [Multi-trip
        tours](https://developers.kardinal.ai/guides/multi-trip-tours) if
        reloading at a depot applies).
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `capacity`.
          enum:
            - capacity
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        capacity:
          type: string
          description: The capacity's name the constraint is linked to.
          example: weight
        overCapacity:
          description: The exceeding capacity.
          type: number
      required:
        - type
        - capacity
        - overCapacity
    AtLeastOneValidCapacityViolation:
      type: object
      description: Violation of an AtLeastOneValidCapacity constraint.
      properties:
        type:
          type: string
          description: >-
            Discriminator identifying this violation as
            `atLeastOneValidCapacity`.
          enum:
            - atLeastOneValidCapacity
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        name:
          description: >-
            The name of the AtLeastOneValidCapacity constraint the violation is
            linked to.
          type: string
          example: capacityCheck1
        overCapacities:
          allOf:
            - $ref: '#/components/schemas/Capacities'
      required:
        - type
        - name
        - overCapacities
    SuccessiveStopsViolation:
      type: object
      description: Violation of an order's successive-stops constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `successiveStops`.
          enum:
            - successiveStops
        expectedSuccessiveStopIds:
          description: The stop ids in the expected order.
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop1
            - stop2
        interleavedStopIds:
          description: >-
            The stop ids which are not expected and interleaved between the
            order stops.
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop3
      required:
        - type
        - expectedSuccessiveStopIds
    OrderViolation:
      type: object
      description: Violation of an order's stop-sequence constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `order`.
          enum:
            - order
        expectedOrderedStopIds:
          description: The stop ids in the expected order.
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop1
            - stop2
        missedStopIds:
          description: The stop ids missing from the tour.
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop2
        badlyOrderedStopIds:
          description: The stop ids badly ordered in the tour.
          type: array
          items:
            type: string
            allOf:
              - $ref: '#/components/schemas/RegexIdValidation'
          example:
            - stop2
            - stop1
      required:
        - type
        - expectedOrderedStopIds
    MaxStopSpanViolation:
      type: object
      description: Violation of an order's MaxStopSpan constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxStopSpan`.
          enum:
            - maxStopSpan
        orderId:
          description: The order id with the MaxStopSpan constraint violation.
          type: string
          example: order1
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        delay:
          description: The delay that exceeds the MaxStopSpan.
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - type
        - orderId
        - delay
    WorkingTimeWindowViolation:
      type: object
      description: Violation of a resource's TimeWindow constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `workingTimeWindow`.
          enum:
            - workingTimeWindow
        delay:
          description: The delay that exceeds the resource's TimeWindow.
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - type
        - delay
    MaxWorkingDurationViolation:
      type: object
      description: >
        Violation of a resource's MaxWorkingDuration constraint.


        > **Modelling pitfall.** Check `exceededDuration` against the resource's
        `maxWorkingDuration`: either the resource is assigned too much work for
        its allowed shift length, or `maxWorkingDuration` itself needs raising
        if the shift was underestimated.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxWorkingDuration`.
          enum:
            - maxWorkingDuration
        maxWorkingDuration:
          description: The expected maximum working duration.
          allOf:
            - $ref: '#/components/schemas/Duration'
        exceededDuration:
          description: The duration that exceeds the maximum working duration.
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - type
        - maxWorkingDuration
        - exceededDuration
    MaxDistanceInKmViolation:
      type: object
      description: Violation of a resource's MaxDistanceInKm constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxDistanceInKm`.
          enum:
            - maxDistanceInKm
        maxDistanceInKm:
          description: The expected maximum distance, in km.
          type: number
          example: 200
        exceededDistanceInKm:
          description: The distance that exceeds the maximum distance, in km.
          type: number
          example: 15
      required:
        - type
        - maxDistanceInKm
        - exceededDistanceInKm
    MaxInterStopDistanceInKmViolation:
      type: object
      description: Violation of a resource's MaxInterStopDistanceInKm constraint.
      properties:
        type:
          type: string
          description: >-
            Discriminator identifying this violation as
            `maxInterStopDistanceInKm`.
          enum:
            - maxInterStopDistanceInKm
        wayPointIndex:
          type: integer
          description: The index of the waypoint the violation applies to.
          example: 0
        maxInterStopDistanceInKm:
          description: The expected maximum inter-stop distance, in km.
          type: number
          example: 50
        exceededDistanceInKm:
          description: The inter-stop distance that exceeds the maximum distance, in km.
          type: number
          example: 5
      required:
        - type
        - maxInterStopDistanceInKm
        - exceededDistanceInKm
    MaxInterStopDurationViolation:
      type: object
      description: Violation of a resource's MaxInterStopDuration constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxInterStopDuration`.
          enum:
            - maxInterStopDuration
        wayPointIndex:
          type: integer
          description: The index 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
    StopIncompatibilityViolation:
      type: object
      description: Violation of a resource's StopIncompatibility constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `stopIncompatibility`.
          enum:
            - stopIncompatibility
        name:
          description: >-
            The name of the StopIncompatibility constraint the violation is
            linked to.
          type: string
          example: noOverlap1
        incompatibilities:
          description: Lists of stop ids for each incompatible tag.
          type: array
          items:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/RegexIdValidation'
              example:
                - stop1
                - stop2
            minItems: 2
            maxItems: 2
        tags:
          allOf:
            - $ref: '#/components/schemas/StopTagPair'
      required:
        - type
        - incompatibilities
        - tags
    AtLeastOneConstraintViolation:
      type: object
      description: Violation of a resource's AtLeastOneConstraint constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `atLeastOneConstraint`.
          enum:
            - atLeastOneConstraint
        name:
          description: >-
            The name of the AtLeastOneConstraint constraint the violation is
            linked to.
          type: string
          example: orConstraint1
        violatedConstraints:
          description: Lists of sub-constraints violations.
          type: array
          items:
            $ref: '#/components/schemas/TourViolation'
      required:
        - type
        - name
        - violatedConstraints
    MaxStopTagGroupsViolation:
      type: object
      description: Violation of a resource's MaxStopTagGroups constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `maxStopTagGroups`.
          enum:
            - maxStopTagGroups
        name:
          description: >-
            The name of the MaxStopTagGroups constraint the violation is linked
            to.
          type: string
          example: maxDepotVisits
        exceededNbGroupsByStopTag:
          type: object
          description: The exceeded number of groups by stop tag.
          additionalProperties:
            allOf:
              - $ref: '#/components/schemas/ExceededNbGroups'
          example:
            depot:
              maxAllowed: 2
              exceededNbGroups: 1
      required:
        - type
        - exceededNbGroupsByStopTag
    RemovalStrategyViolation:
      type: object
      description: Violation of a resource's RemovalStrategy constraint.
      properties:
        type:
          type: string
          description: Discriminator identifying this violation as `removalStrategy`.
          enum:
            - removalStrategy
        name:
          description: >-
            The name of the RemovalStrategy constraint the violation is linked
            to.
          type: string
          example: lifoRule1
        removalStrategyType:
          allOf:
            - $ref: '#/components/schemas/RemovalStrategyType'
      required:
        - type
        - removalStrategyType
    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
    WayPointStatus:
      type: string
      description: >
        How a waypoint's timing was determined: `fixed` and `assigned` carry
        over the corresponding `AssignmentStatus` from the input `state`, while
        `optimized` means the engine chose the timing itself.
      enum:
        - fixed
        - assigned
        - optimized
      default: fixed
    WaypointViolation:
      description: >
        The subset of `TourViolation` kinds that attach to one specific waypoint
        rather than to the tour as a whole. Branch on `type` to read the fields
        specific to that violation kind, or handle an unrecognized `type`
        generically without inspecting its other fields.
      oneOf:
        - $ref: '#/components/schemas/BeginViolation'
        - $ref: '#/components/schemas/EndViolation'
        - $ref: '#/components/schemas/SkillsViolation'
        - $ref: '#/components/schemas/ForbiddenAssignmentViolation'
        - $ref: '#/components/schemas/AuthorizedTimeWindowViolation'
        - $ref: '#/components/schemas/CapacityViolation'
        - $ref: '#/components/schemas/AtLeastOneValidCapacityViolation'
        - $ref: '#/components/schemas/MaxInterStopDistanceInKmViolation'
        - $ref: '#/components/schemas/MaxInterStopDurationViolation'
      discriminator:
        propertyName: type
        mapping:
          begin: '#/components/schemas/BeginViolation'
          end: '#/components/schemas/EndViolation'
          skills: '#/components/schemas/SkillsViolation'
          forbiddenAssignment: '#/components/schemas/ForbiddenAssignmentViolation'
          authorizedTimeWindow: '#/components/schemas/AuthorizedTimeWindowViolation'
          capacity: '#/components/schemas/CapacityViolation'
          atLeastOneValidCapacity: '#/components/schemas/AtLeastOneValidCapacityViolation'
          maxInterStopDistanceInKm: '#/components/schemas/MaxInterStopDistanceInKmViolation'
          maxInterStopDuration: '#/components/schemas/MaxInterStopDurationViolation'
    FromPrevious:
      type: object
      description: >-
        The travel distance and duration from the previous waypoint to the
        current one.
      properties:
        travelDistanceInKm:
          type: number
          description: Distance travelled from the previous waypoint, in kilometres.
          example: 2.3269331
        travelDuration:
          description: Time spent travelling from the previous waypoint.
          allOf:
            - $ref: '#/components/schemas/Duration'
      required:
        - travelDistanceInKm
        - travelDuration
      example:
        travelDistanceInKm: 2.3269331
        travelDuration: PT4M
    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
    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
    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.
    ForbiddenAssignment:
      type: object
      description: Forbidden assignment 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'
      required:
        - resourceTag
        - stopTag
    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
    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
    ExceededNbGroups:
      type: object
      description: >-
        The maximum number of groups and its corresponding exceeding number of
        groups, for a stop tag.
      properties:
        maxAllowed:
          type: integer
          description: Maximum number of groups allowed.
          example: 2
          minimum: 0
        exceededNbGroups:
          type: integer
          description: Number of groups that exceeds the maximum number allowed.
          example: 2
          minimum: 1
      required:
        - maxAllowed
        - exceededNbGroups
    RemovalStrategyType:
      type: string
      description: >-
        Unloading order enforced by an `AdditionalConstraintRemovalStrategy`.
        `lifo` is currently the only supported strategy.
      enum:
        - lifo
      default: lifo
    CountryCode:
      type: string
      description: A country's standard name, Alpha-2 code, or Alpha-3 code.
      example: Switzerland
  responses:
    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
    NotFound:
      description: >
        The specified resource was not found (`code: NOT_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 the existence of
        resources the caller can't access).


        On `GET /plans/{planId}/solution`, only `properties.details` tells two
        cases apart: `Plan not found` means the plan doesn't exist or was
        deleted; `Solution version not found.` means the plan exists but has no
        solution yet, as while it's `waiting` or `processing`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
          examples:
            notFound:
              summary: NOT_FOUND
              value:
                errors:
                  - code: NOT_FOUND
                    message: The requested object could not be found.
    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 <token>`. Two kinds of
        token are accepted:


        - A **session token** (1 hour), obtained through the interactive Console
        login flow. Used to sign in to the Console; not meant to be used against
        this API.

        - A **long-term API token** (366 days), obtained once via the Console
        and meant to be stored by your integration. It is the credential
        recommended for backend use, since it does not depend on repeating the
        interactive login flow.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.