openapi: 3.0.0
info:
  title: Vehicle events API
  description: This document lists Autopass external vehicle events endpoints.
  version: 1.0.4
servers:
  - url: https://api.autopass.pro
    description: Live server
    x-environment: live
  - url: https://api-prelive.autopass.pro
    description: Prelive server
    x-environment: prelive
paths:
  /events/vin/{vin}:
    get:
      summary: List VIN events
      description: List events for a given VIN.
      operationId: list-vin-events
      parameters:
        - in: path
          name: vin
          required: true
          schema:
            type: string
            example: VF109876543212345
        - $ref: "#/components/parameters/PaginationLimit"
        - $ref: "#/components/parameters/PaginationOffset"
      responses:
        200:
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventCollection"
        400:
          description: Bad Request – invalid VIN or query parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized – missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden – valid token but insufficient permissions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /events/vin/{vin}/meta:
    get:
      summary: Get VIN meta information
      description: Get only meta information for a given VIN.
      operationId: get-vin-meta-information
      parameters:
        - in: path
          name: vin
          required: true
          schema:
            type: string
            example: VF109876543212345
        - $ref: "#/components/parameters/PaginationLimit"
        - $ref: "#/components/parameters/PaginationOffset"
      responses:
        200:
          description: OK.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaOnly"
        400:
          description: Bad Request – invalid VIN or query parameters.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized – missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden – valid token but insufficient permissions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
  - BearerAuth: []
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: access_token
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Access-Token
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    PaginationLimit:
      in: query
      name: limit
      example: 20
      schema:
        type: integer
      description: Limits results to given limit.
    PaginationOffset:
      in: query
      name: offset
      example: 10
      schema:
        type: integer
      description: List results starting to given offset.
  schemas:
    Meta:
      type: object
      properties:
        limit:
          type: integer
          example: 100
        offset:
          type: integer
          example: 20
        total:
          type: integer
          example: 200
    EventDescriptionItem:
      type: object
      properties:
        code:
          type: integer
          example: 199
        name:
          type: string
          example: Wheel mount
        label:
          type: string
          example: ""
    Event:
      type: object
      properties:
        id:
          type: string
          example: "1"
        date:
          type: string
          format: date
          example: 2019-10-08
        mileage:
          type: number
          nullable: true
          example: null
        description:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/EventDescriptionItem"
          example:
            a1: { code: 1, name: "Wheel", label: "" }
            b1: { code: 19, name: "Wheel mount", label: "" }
            c1: { code: 199, name: "Wheel mount", label: "" }
        source:
          type: string
          example: NORPOR
    Events:
      type: array
      items:
        $ref: "#/components/schemas/Event"
    EventCollection:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
        events:
          $ref: "#/components/schemas/Events"
    MetaOnly:
      type: object
      properties:
        meta:
          $ref: "#/components/schemas/Meta"
    Error:
      type: object
      properties:
        key:
          type: string
          example: ERR_AUTH
        message:
          type: string
          example: user for the given token does not exist
        details:
          nullable: true
          example: null
