> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a simple plan



## OpenAPI

````yaml /openapi.yaml post /agencies/{agencyId}/simplePlans
openapi: 3.0.3
info:
  title: Kardinal ARO 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: Authenticate
    description: How to authenticate, and manage the access and refresh tokens.
  - name: Plan
    description: How to create, retrieve, update and delete plans.
  - name: Resource
    description: How to create, retrieve, update and delete resources in a plan.
  - name: Order
    description: How to create, retrieve, update and delete orders in a plan.
  - name: SimplePlan
    description: How to create a plan through the use of a simple plan.
paths:
  /agencies/{agencyId}/simplePlans:
    parameters:
      - $ref: '#/components/parameters/agencyId'
    post:
      tags:
        - SimplePlan
      summary: Create a simple plan
      operationId: postSimplePlan
      requestBody:
        description: The SimplePlan to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePlan'
      responses:
        '201':
          description: The simple plan was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedSimplePlan'
        '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'
components:
  parameters:
    agencyId:
      name: agencyId
      description: The agency id.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AgencyId'
  schemas:
    SimplePlan:
      type: object
      description: >-
        A simple plan is a simplified representation of a plan, with simplified
        resources, simplified stops, and a simplified objective.
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        version:
          $ref: '#/components/schemas/PlanVersion'
        state:
          $ref: '#/components/schemas/PlanState'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/SimpleResource'
        nbResources:
          type: number
          format: integer
          minimum: 0
          readOnly: true
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/SimpleStop'
        nbStops:
          type: number
          format: integer
          minimum: 0
          readOnly: true
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        objective:
          $ref: '#/components/schemas/SimpleObjective'
        tz:
          $ref: '#/components/schemas/TimeZone'
        lateDeparture:
          description: True if lateDeparture is requested for Resources, false otherwise.
          type: boolean
          default: false
        createdAt:
          description: The plan's creation datetime.
          nullable: false
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
        createdBy:
          type: string
          description: The username of the user who created this simple plan
          nullable: false
          readOnly: true
        updatedAt:
          description: The plan's last update datetime.
          nullable: true
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/DateTime'
        updatedBy:
          type: string
          description: The username of the user who last updated this simple plan
          nullable: true
          readOnly: true
        archivedAt:
          description: 'The plan''s archiving datetime: if not null, the plan is archived.'
          nullable: true
          readOnly: true
          example: null
          allOf:
            - $ref: '#/components/schemas/DateTime'
      required:
        - id
        - agencyId
        - resources
    EnvelopedSimplePlan:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/SimplePlan'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
        planVersion:
          $ref: '#/components/schemas/PlanVersion'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    AgencyId:
      description: The agency id.
      readOnly: true
      example: LND_Agency-42
      allOf:
        - $ref: '#/components/schemas/RegexPrefixedIdValidation'
    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
    PlanVersion:
      type: integer
      description: The plan version.
      readOnly: true
      minimum: 1
      example: 42
    PlanState:
      type: string
      readOnly: true
      description: |
        The corresponding plan's state.
          - waiting: The plan was received and is awaiting processing.
          - processing: The plan is being processed.
          - preOptimizing: The plan is being optimized while awaiting traffic or other information.
          - preOptimized: While still awaiting traffic or other information, one of the following events has occurred:
              no better solution can be produced, or the optimization period has reached its limit.
              Note that 'preOptimized' should be followed by 'optimizing' and 'optimized'.
          - optimizing: The plan is being optimized with all required information.
          - optimized: This state can be triggered by one of the following events:
              no better solution can be produced, or the optimization period has reached its limit.
          - stopped: The plan's awaiting optimizations were canceled.
          - deleted: The plan was deleted and awaiting optimizations were canceled.
          - interrupted: The plan was either updated, stopped or deleted during its optimization.
      enum:
        - waiting
        - processing
        - preOptimizing
        - preOptimized
        - optimizing
        - optimized
        - stopped
        - deleted
        - interrupted
    SimpleResource:
      type: object
      properties:
        id:
          description: Resource ids must be unique within a plan.
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        capacities:
          $ref: '#/components/schemas/Capacities'
        departure:
          $ref: '#/components/schemas/Position'
        arrival:
          oneOf:
            - $ref: '#/components/schemas/Position'
            - $ref: '#/components/schemas/AtFirstPositionArrival'
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        workingTimeWindow:
          $ref: '#/components/schemas/TimeWindow'
        maxWorkingDuration:
          $ref: '#/components/schemas/Duration'
        maxDistanceInKm:
          type: number
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        breaks:
          type: array
          items:
            $ref: '#/components/schemas/Break'
      required:
        - id
        - workingTimeWindow
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    SimpleStop:
      type: object
      properties:
        id:
          description: Single stop ids must be unique within a plan.
          allOf:
            - $ref: '#/components/schemas/RegexIdValidation'
        position:
          $ref: '#/components/schemas/Position'
        kind:
          $ref: '#/components/schemas/StopKind'
        operationDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
        capacities:
          allOf:
            - $ref: '#/components/schemas/Capacities'
        timeWindow:
          $ref: '#/components/schemas/TimeWindow'
      required:
        - id
        - position
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    SimpleObjective:
      type: string
      enum:
        - minimizeResources
        - minimizeWorkingDuration
        - minimizeDistance
      default: minimizeResources
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    TimeZone:
      type: string
      description: >
        The time zone is a string code which identifies a region of the world in
        the "time zone database", also called "tz database".

        The tz database is a partition of the world into regions where local
        clocks all show the same time.

        This database gives the rules for time offset and daylight saving time
        in each region.


        How do we use it?


        In order to work with time events accurately, we usually use datetimes
        in the iso-8601 format, without explicit time zone.

        This format is quite well suported by many programming languages, and it
        is well suited for technical data exchange.

        But it is not easy to use for humans.


        For instance, here are three datetimes in iso-8601 format, which give
        the same exact moment in time:

        - "2025-05-22T05:43:00Z"

        - "2025-05-22T06:43:00+01:00"

        - "2025-05-22T07:43:00+02:00"


        For a non-technical user, it is difficult to know how to relate this to
        the time displayed on a watch or a clock.


        We improve the user experience by adding the support of local datetimes,
        thanks to the use of the time zone,

        which allows to transform a local datetime into an iso-8601 datetime:

        - local datetime + timezone (tz) = iso-8601 datetime


        For instance, here are five datetimes which all give the same exact
        moment in time:

        - "2025-05-22T05:43:00Z"

        - "2025-05-22T06:43:00+01:00"

        - "2025-05-22T07:43:00+02:00"

        - "2025-05-22 07:43:00"       + timezone "tz": "Europe/Paris"

        - "2025-05-22 07:43"          + timezone "tz": "Europe/Paris"


        Note: the last example ("2025-05-22 07:43") illustrates the support of
        local datetimes without seconds,

        which can be very practical for users.


        In order for local datetimes to be supported, some JSON input objects
        contain a "tz" time zone property.

        This "tz" property is used to pre-process the JSON input payload, like
        this:

        - We check if a valid timezone can be extracted from the "tz" property,

        - If so, we perform the following actions:
          - Walk through the whole JSON content to look for local datetimes,
          - Use the timezone to transform each local datetime into an iso-8601 datetime.

        Important: some objects contain a "properties" sub-object, which is a
        map of custom client data;

        the content of the "properties" sub-objects is always excluded from the
        time zone pre-processing.
      externalDocs:
        url: https://www.iana.org/time-zones
      example: Europe/Paris
    DateTime:
      type: string
      description: >-
        A full calendar date time, expressed in the ISO8601 **date** format:
        YYYY-MM-DDThh:mm:ssZ.
      example: '2019-11-15T12:34:56Z'
    PlanId:
      description: The plan id.
      readOnly: true
      example: plan-AB
      allOf:
        - $ref: '#/components/schemas/RegexIdValidation'
    EnvelopedErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    RegexPrefixedIdValidation:
      type: string
      description: An id beginning with a prefix and an underscore.
      pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$
    RegexIdValidation:
      type: string
      description: >-
        At least one character among those allowed: unaccented alpha-numeric
        characters, "-", ".", "_", "~", ":", "@", "!", "$", ",".
      pattern: ^[a-zA-Z0-9-._~:@!$,]+$
    Capacities:
      type: object
      additionalProperties:
        type: number
      example:
        volume: 9.5
        weight: 2200
        nbPackages: 23
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Position:
      type: object
      properties:
        lon:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude coordinate.
        lat:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude coordinate.
      required:
        - lon
        - lat
      example:
        lon: 2.3269331
        lat: 48.8812658
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    AtFirstPositionArrival:
      type: string
      description: The resource must go back to it's Tour first position.
      enum:
        - atFirstPosition
    TimeWindow:
      type: object
      properties:
        begin:
          $ref: '#/components/schemas/DateTime'
        end:
          $ref: '#/components/schemas/DateTime'
      required:
        - begin
        - end
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    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
    Break:
      oneOf:
        - $ref: '#/components/schemas/TimeWindowBreak'
        - $ref: '#/components/schemas/TravelDurationSlidingBreak'
        - $ref: '#/components/schemas/WorkingDurationSlidingBreak'
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    StopKind:
      type: string
      enum:
        - pickup
        - delivery
        - acknowledgement
      default: delivery
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    Error:
      type: object
      readOnly: true
      properties:
        code:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        message:
          type: string
          description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
        properties:
          $ref: '#/components/schemas/ErrorProperties'
      required:
        - message
        - code
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
    TimeWindowBreak:
      type: object
      description: A required break of a given duration in a given time window.
      properties:
        type:
          type: string
          enum:
            - timeWindowBreak
          description: >-
            Discriminator value: "timeWindowBreak". A standard break (e.g.
            lunch) defined by a fixed time frame.
        duration:
          allOf:
            - $ref: '#/components/schemas/Duration'
          description: The duration (ISO 8601) of the break.
        timeWindow:
          allOf:
            - $ref: '#/components/schemas/TimeWindow'
          description: >-
            The time frame within which the break must be taken. Acts similarly
            to a workingTimeWindow combined with a maxWorkingDuration.
      required:
        - duration
        - timeWindow
    TravelDurationSlidingBreak:
      type: object
      description: Limitation rule on max travel duration without any break.
      properties:
        type:
          type: string
          enum:
            - travelDurationSlidingBreak
          description: >-
            Discriminator value: "travelDurationSlidingBreak". Represents a
            break tied to driving time, such as a legal break required after a
            maximum amount of driving (for example, a 10-minute break every 4
            hours of driving).
        minBreakDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
          description: The minimum duration of the break.
        maxInterBreakDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
          description: The maximum duration of travel allowed between two breaks.
      required:
        - type
        - minBreakDuration
        - maxInterBreakDuration
    WorkingDurationSlidingBreak:
      type: object
      description: Limitation rule on max working duration without any break.
      properties:
        type:
          type: string
          enum:
            - workingDurationSlidingBreak
          description: >-
            Discriminator value: "workDurationSlidingBreak". Represents a break
            tied to working time, such as a legal break required after a maximum
            amount of work (for example, a 10-minute break every 6 hours of
            work).
        minBreakDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
          description: The minimum duration of the break.
        maxInterBreakDuration:
          allOf:
            - $ref: '#/components/schemas/Duration'
          description: The maximum duration of work allowed between two breaks.
      required:
        - type
        - minBreakDuration
        - maxInterBreakDuration
    ErrorProperties:
      type: object
      additionalProperties:
        type: string
      description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.'
  responses:
    BadRequest:
      description: >-
        The server could not understand the request due to invalid content (bad
        syntax, bad format, bad values, etc).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    NotAuthenticated:
      description: The caller is not authenticated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    Unauthorized:
      description: The caller is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
    InternalServerError:
      description: An internal server error has occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EnvelopedErrors'
  securitySchemes:
    access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT

````