openapi: 3.0.3
info:
  title: INVERS Trips API
  version: 1.0.0
  contact:
    name: INVERS GmbH
    url: https://developers.invers.com
  x-api-id: 8a821d6f-38f5-4295-8ae8-e6ab47157caf
  x-audience: external-public
  description: |-
    The Trips API is intended for INVERS customers who need programmatic access to integrate their applications with the INVERS platform.

    The base URL for all endpoints described here is `https://api.invers.com`.
    Learn more in our [Integration Guide](https://developers.invers.com/integration-guide/) and [common API rules](https://developers.invers.com/integration-guide/api-basics/).
servers:
  - url: https://api.invers.com
    description: INVERS OneAPI
tags:
  - name: Trips
    description: Retrieve trips of vehicles in your fleet
externalDocs:
  description: Find out more about the Trips API in our documentation.
  url: https://developers.invers.com/insights/trips/
paths:
  /trips:
    get:
      tags:
        - Trips
      operationId: getTrips
      summary: Get a list of Trips
      description: |
        Returns a list of Trips.

        The result can be narrowed down using the documented query parameters.

        By default the Trips are sorted by the point in time they ended (most recent Trips first).
      security:
        - OAuth2:
            - VEHICLE_HISTORY
      x-invers-permission: vehicle-history:trips.ro
      parameters:
        - name: from
          description: |
            Only return Trips that started after the given timestamp.
          in: query
          schema:
            type: string
            format: date-time
            example: '2025-10-21T11:54:05Z'
        - name: until
          description: |
            Only return Trips that ended before the given timestamp.
          in: query
          schema:
            type: string
            format: date-time
            example: '2025-10-21T13:54:05Z'
        - name: vehicle_id
          description: |
            Only return Trips for this specific vehicle.
          in: query
          schema:
            type: string
            maxLength: 12
            example: JQ7RP
        - name: limit
          in: query
          description: Number of items to return at most.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 500
            default: 100
            example: 20
        - name: cursor
          in: query
          description: |
            The cursor object used to navigate through the results. Do not provide
            any other search-related query parameters when using the cursor.
          required: false
          schema:
            type: string
            example: eyJ2IjpbIjIwMjAtMTEtMTZUMDk6NTc6MjUuNzY2MDAwMFoiLCJaOTVSUyJdLCJkIjpmYWxzZSwicSI6eyJsIjozfX0=
      responses:
        '200':
          description: The requested list of Trips.
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    description: The list of Trips.
                    type: array
                    maxItems: 500
                    items:
                      $ref: '#/components/schemas/trip'
                  cursors:
                    $ref: '#/components/schemas/cursors'
              examples:
                tripList:
                  $ref: '#/components/examples/tripListExample'
        '400':
          description: The request was invalid. See examples for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Invalid time range:
                  value:
                    type: /problems/validation-error
                    type_documentation: https://developers.invers.com/problems/validation-error
                    title: Validation Error
                    status: 400
                    detail: The timestamp 'from' must be before the timestamp 'until'.
                    flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
                Invalid query parameters:
                  $ref: '#/components/examples/invalidQueryParameters'
                Invalid cursor:
                  $ref: '#/components/examples/invalidCursor'
  /trips/{id}:
    get:
      tags:
        - Trips
      operationId: getTrip
      summary: Get a specific Trip
      description: |
        Returns the Trip identified by its `id`.
      security:
        - OAuth2:
            - VEHICLE_HISTORY
      x-invers-permission: vehicle-history:trips.ro
      parameters:
        - name: id
          required: true
          description: The ID of a trip
          in: path
          schema:
            type: string
            maxLength: 12
            example: H5XAV
      responses:
        '200':
          description: The requested Trip.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trip'
              examples:
                trip:
                  $ref: '#/components/examples/tripExample'
        '404':
          description: The trip with the given ID was not found. See examples for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: /problems/resource-not-found
                type_documentation: https://developers.invers.com/problems/resource-not-found
                title: The requested resource cannot be found.
                status: 404
                detail: The trip with ID 'D23PV' cannot be found.
                flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
  /vehicles/{vehicle_id}/trips/latest:
    get:
      tags:
        - Trips
      operationId: getLatestTrip
      summary: Get the latest Trip
      description: |
        Returns the latest Trip for the vehicle with ID `vehicle_id`.
        Only Trips that have ended are returned.
        If the vehicle is currently used for a Trip, this Trip will only be returned once it has ended.
      security:
        - OAuth2:
            - VEHICLE_HISTORY
      x-invers-permission: vehicle-history:trips.ro
      parameters:
        - name: vehicle_id
          required: true
          description: Unique ID of the vehicle.
          in: path
          schema:
            type: string
            maxLength: 12
            example: JQ7RP
      responses:
        '200':
          description: The latest Trip of the vehicle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trip'
              examples:
                trip:
                  $ref: '#/components/examples/tripExample'
        '404':
          description: No trip was found for the vehicle. See examples for more details.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                Vehicle not found:
                  value:
                    type: /problems/resource-not-found
                    type_documentation: https://developers.invers.com/problems/resource-not-found
                    title: The requested resource cannot be found.
                    status: 404
                    detail: The vehicle with ID 'MT3T3' cannot be found.
                    flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
                No trip for vehicle:
                  value:
                    type: /problems/resource-not-found
                    type_documentation: https://developers.invers.com/problems/resource-not-found
                    title: The requested resource cannot be found.
                    status: 404
                    detail: The vehicle with ID 'MT3T3' has no latest trip.
                    flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /auth/oauth/token
          scopes:
            VEHICLE_HISTORY: Read access to historical vehicle data
        authorizationCode:
          authorizationUrl: /auth/oauth/authorize
          tokenUrl: /auth/oauth/token
          scopes:
            VEHICLE_HISTORY: Read access to historical vehicle data
  schemas:
    problem:
      $ref: '#/components/schemas/Problem'
    trip:
      type: object
      description: All details regarding a Trip.
      required:
        - id
        - vehicle_id
        - trigger
        - start
        - end
        - metrics
      properties:
        id:
          $ref: '#/components/schemas/tripShortId'
        vehicle_id:
          $ref: '#/components/schemas/vehicleId'
        vehicle_master_data:
          $ref: '#/components/schemas/vehicle_master_data'
        trigger:
          $ref: '#/components/schemas/tripTrigger'
        start:
          $ref: '#/components/schemas/tripStart'
        end:
          $ref: '#/components/schemas/tripEnd'
        metrics:
          $ref: '#/components/schemas/tripMetrics'
    tripStart:
      type: object
      description: Contains all data related to the start of the trip.
      required:
        - occurred_at
        - triggered_by
      properties:
        occurred_at:
          type: string
          format: date-time
          example: '2020-10-08T10:29:00.321Z'
          description: UTC time of when the event that started the trip occurred.
        position:
          type: object
          description: The position of the vehicle where the trip started. Trips should usually have a position.
          required:
            - timestamp
            - value
          properties:
            timestamp:
              type: string
              format: date-time
              example: '2021-03-08T10:29:00.321Z'
              description: UTC time of the value as recorded by the vehicle (or the best approximation thereof).
            value:
              $ref: '#/components/schemas/positionValue'
        state_of_charge_or_fuel_level_in_percent:
          description: Fuel level or state of charge of the vehicle at the start of the trip.
          allOf:
            - $ref: '#/components/schemas/StatePropertyBase'
            - $ref: '#/components/schemas/PercentageValue'
        triggered_by:
          type: object
          description: Describes what triggered the event that caused the trip to start.
          required:
            - channel
            - correlation_id
          properties:
            channel:
              type: string
              x-extensible-enum:
                - RFID_TAG_READ
                - RENTAL_STATUS
                - API_COMMAND
                - BLUETOOTH
                - AUTO_IMMOBILIZER_CONTROL
                - IGNITION_CHANGED
                - DRIVING_ENABLED_CHANGED
              example: RFID_TAG_READ
              description: Name of the channel that was used to trigger the event.
            correlation_id:
              type: string
              description: |-
                * If `channel` is `RFID_TAG_READ` this property includes the ID of the RFID tag
                  that triggered the event.
                * If `channel` is `RENTAL_STATUS` this property includes the ID of the rental.
                * If `channel` is `API_COMMAND` this property includes the X-INVERS-Flow-ID of the API command
                  that triggered the event.
                * If `channel` is `BLUETOOTH` this property includes the ID of the Bluetooth token
                  that was used to communicate with the vehicle and therefore, triggered the event.
                * If `channel` is `AUTO_IMMOBILIZER_CONTROL` this property includes the X-INVERS-Flow-ID of the generated event.
                * If `channel` is `IGNITION_CHANGED` this property includes the X-INVERS-Flow-ID of the generated event.
                * If `channel` is `DRIVING_ENABLED_CHANGED` this property includes the X-INVERS-Flow-ID of the generated event.
              example: 0000000084BAFE7E
          example:
            channel: RFID_TAG_READ
            correlation_id: 0000000084BAFE7E
    tripEnd:
      type: object
      description: Contains all data related to the end of the trip.
      required:
        - occurred_at
        - triggered_by
      properties:
        occurred_at:
          type: string
          format: date-time
          example: '2020-10-08T10:29:00.321Z'
          description: UTC time of when the event that ended the trip occurred.
        position:
          type: object
          description: The position of the vehicle where the trip ended. Trips should usually have a position.
          required:
            - timestamp
            - value
          properties:
            timestamp:
              type: string
              format: date-time
              example: '2021-03-08T10:29:00.321Z'
              description: UTC time of the value as recorded by the vehicle (or the best approximation thereof).
            value:
              $ref: '#/components/schemas/positionValue'
        state_of_charge_or_fuel_level_in_percent:
          description: Fuel level or state of charge of the vehicle at the end of the trip.
          allOf:
            - $ref: '#/components/schemas/StatePropertyBase'
            - $ref: '#/components/schemas/PercentageValue'
        triggered_by:
          type: object
          description: Describes what triggered the event that caused the trip to end.
          required:
            - channel
            - correlation_id
          properties:
            channel:
              type: string
              x-extensible-enum:
                - RFID_TAG_READ
                - RENTAL_STATUS
                - API_COMMAND
                - BLUETOOTH
                - AUTO_IMMOBILIZER_CONTROL
                - IGNITION_CHANGED
                - DRIVING_ENABLED_CHANGED
              example: RFID_TAG_READ
              description: Name of the channel that was used to trigger the event.
            correlation_id:
              type: string
              description: |-
                * If `channel` is `RFID_TAG_READ` this property includes the ID of the RFID tag
                  that triggered the event.
                * If `channel` is `RENTAL_STATUS` this property includes the ID of the rental.
                * If `channel` is `API_COMMAND` this property includes the X-INVERS-Flow-ID of the API command
                  that triggered the event.
                * If `channel` is `BLUETOOTH` this property includes the ID of the Bluetooth token
                  that was used to communicate with the vehicle and therefore, triggered the event.
                * If `channel` is `AUTO_IMMOBILIZER_CONTROL` this property includes the X-INVERS-Flow-ID of the generated event.
                * If `channel` is `IGNITION_CHANGED` this property includes the X-INVERS-Flow-ID of the generated event.
                * If `channel` is `DRIVING_ENABLED_CHANGED` this property includes the X-INVERS-Flow-ID of the generated event.
              example: 0000000084BAFE7E
    tripMetrics:
      type: object
      description: The metrics that were recorded during the trip.
      properties:
        duration_in_seconds:
          $ref: '#/components/schemas/duration_in_seconds'
        distance_in_kilometers:
          $ref: '#/components/schemas/distance_in_kilometers'
    tripShortId:
      type: string
      maxLength: 12
      example: H5XAVTP
      description: Unique ID of the trip
    vehicleId:
      type: string
      maxLength: 12
      description: Unique ID of the vehicle.
      example: JQ7RP
    vehicle_master_data:
      type: object
      description: Additional information about the vehicle.
      properties:
        vin:
          type: string
          description: The VIN (vehicle identification number) of the vehicle.
        license_plate:
          type: string
          description: The license plate of the vehicle.
        brand:
          type: string
          description: The brand of the vehicle.
        model:
          type: string
          description: The model of the vehicle.
        custom_name:
          type: string
          description: A custom name for the vehicle. This field is managed by the user and can therefore contain any text.
    tripTrigger:
      type: string
      maxLength: 64
      description: |
        The trigger that started and ended the trip.
      x-extensible-enum:
        - RENTAL_STATUS
        - IGNITION
        - DRIVING_ENABLED
      example: DRIVING_ENABLED
    positionValue:
      type: object
      description: Position of vehicle (GPS/GLONASS/...).
      required:
        - lat
        - lon
      properties:
        lat:
          minimum: -90
          maximum: 90
          type: number
          example: 50.123
          format: double
          description: Latitude of the position.
        lon:
          minimum: -180
          maximum: 180
          type: number
          example: 7.321
          format: double
          description: Longitude of the position.
    StatePropertyBase:
      type: object
      required:
        - timestamp
        - value
      properties:
        timestamp:
          type: string
          format: date-time
          example: '2021-03-08T10:29:00Z'
          description: UTC time of the value as recorded by the vehicle (or the best approximation thereof).
    PercentageValue:
      required:
        - value
      properties:
        value:
          type: integer
          minimum: 0
          maximum: 100
          example: 100
          format: int32
          description: Percentage ranging from 0 to 100.
    duration_in_seconds:
      type: integer
      format: int64
      minimum: 0
      example: 1800
      description: The duration of the trip in seconds.
    distance_in_kilometers:
      type: number
      format: double
      example: 23.4
      minimum: 0
      description: The number of kilometers that were driven during the trip.
    cursors:
      description: |
        Contains the relevant cursors for the returned page -
        prev and next are omitted if they are not applicable.

        Usually the "next" cursor is used repeatedly to iterate the result list.
      type: object
      required:
        - self
      properties:
        self:
          description: |
            Use as `cursor` query parameter in order to retrieve the same batch of results
            as currently returned (according to the limit parameter previously provided).
          type: string
          example: eyJ2IjpbIjIwMjAtMTEtMTZUMDk6NTc6MjUuNDUwMDAwMFoiLCJOWUNOVSJdLCJkIjpmYWxzZSwicSI6eyJsIjozfX0=
        prev:
          description: |
            Use as `cursor` query parameter in order to retrieve the previous batch of results
            (according to the limit parameter previously provided).
          type: string
          example: eyJ2IjpbIjIwMjAtMTEtMTZUMDk6NTc6MjUuNTYxMDAwMFoiLCJOVEY1VCJdLCJkIjp0cnVlLCJxIjp7ImwiOjN9fQ==
        next:
          description: |
            Use as `cursor` query parameter in order to retrieve the next batch of results
            (according to the limit parameter previously provided).
          type: string
          example: eyJ2IjpbIjIwMjAtMTEtMTZUMDk6NTc6MjUuNzY2MDAwMFoiLCJaOTVSUyJdLCJkIjpmYWxzZSwicSI6eyJsIjozfX0=
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - detail
      properties:
        type:
          type: string
          format: uri-reference
          description: |
            A relative URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.
          default: about:blank
          example: /problem/connection-error
        type_documentation:
          type: string
          format: url
          description: |
            An URL that points to a human-readable documentation of the problem type. Some explanations of the problem type together with possible solutions can be found there.  Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: https://developers.invers.com/problems/invalid-credentials/
        title:
          type: string
          description: |
            A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: Connection to database timed out
        flow_id:
          type: string
          description: |
            The id of the flow that caused this error.  For more information visit [https://developers.invers.com/integration-guide/api-basics/#flow-id](https://developers.invers.com/integration-guide/api-basics/#flow-id).
  examples:
    tripExample:
      value:
        id: H5XAV
        vehicle_id: JQ7RP
        vehicle_master_data:
          vin: R1NBDNB16J1000135
          license_plate: RKL-832
          brand: Audi
          model: A3
        trigger: DRIVING_ENABLED
        start:
          occurred_at: '2025-10-21T11:42:26.558Z'
          position:
            timestamp: '2025-10-21T11:42:26.558Z'
            value:
              lat: 50.049866
              lon: 8.561182
          state_of_charge_or_fuel_level_in_percent:
            timestamp: '2025-10-21T11:42:26.558Z'
            value: 85
          triggered_by:
            channel: RFID_TAG_READ
            correlation_id: 0000000084BAFE7E
        end:
          occurred_at: '2025-10-21T13:40:15.571Z'
          position:
            timestamp: '2025-10-21T13:40:15.571Z'
            value:
              lat: 50.910478
              lon: 8.067589
          state_of_charge_or_fuel_level_in_percent:
            timestamp: '2025-10-21T11:42:26.558Z'
            value: 10
          triggered_by:
            channel: RFID_TAG_READ
            correlation_id: 0000000084BAFE7E
        metrics:
          duration_in_seconds: 7069
          distance_in_kilometers: 140.2
    tripListExample:
      value:
        items:
          - id: H5XAV
            vehicle_id: JQ7RP
            vehicle_master_data:
              vin: R1NBDNB16J1000135
              license_plate: RKL-832
              brand: Audi
              model: A3
            trigger: DRIVING_ENABLED
            start:
              occurred_at: '2025-10-21T11:42:26.558Z'
              position:
                timestamp: '2025-10-21T11:42:26.558Z'
                value:
                  lat: 50.049866
                  lon: 8.561182
              state_of_charge_or_fuel_level_in_percent:
                timestamp: '2025-10-21T11:42:26.558Z'
                value: 85
              triggered_by:
                channel: RFID_TAG_READ
                correlation_id: 0000000084BAFE7E
            end:
              occurred_at: '2025-10-21T13:40:15.571Z'
              position:
                timestamp: '2025-10-21T13:40:15.571Z'
                value:
                  lat: 50.910478
                  lon: 8.067589
              state_of_charge_or_fuel_level_in_percent:
                timestamp: '2025-10-21T11:42:26.558Z'
                value: 10
              triggered_by:
                channel: RFID_TAG_READ
                correlation_id: 0000000084BAFE7E
            metrics:
              duration_in_seconds: 7069
              distance_in_kilometers: 140.2
        cursors:
          self: eyJ2IjpbIjIwMjAtMTEtMTZUMDk6NTc6MjUuNDUwMDAwMFoiLCJOWUNOVSJdLCJkIjpmYWxzZSwicSI6eyJsIjozfX0=
    invalidQueryParameters:
      value:
        type: /problems/validation-error
        type_documentation: https://developers.invers.com/problems/validation-error
        title: Validation Error
        status: 400
        detail: Cannot specify query parameter 'limit' when 'cursor' is used. Do not provide any other search-related query parameters when using the cursor.
        flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
    invalidCursor:
      value:
        type: /problems/validation-error
        type_documentation: https://developers.invers.com/problems/validation-error
        title: Validation Error
        status: 400
        detail: The provided cursor is invalid.
        flow_id: 5e77e3e3-48ab-4955-8ab3-1c62339096ab
