Lytx Safety Events (DriveCam) API

openapi: 3.0.1
info:
  title: Lytx..Management.Api Consent Safety Events (DriveCam) API
  description: 'API for retrieving and updating user consent status, requiring authentication.

    '
  version: 1.0.0
servers:
- url: https://api.lytx.com/consent-management
security:
- bearerAuth: []
tags:
- name: Safety Events (DriveCam)
  description: Retrieves vehicles events data
paths:
  /events/triggers:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return List of Possible Event Triggers
      operationId: Events_GetEventTriggers
      responses:
        '200':
          description: Event triggers retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEventTrigger'
        '204':
          description: No event triggers found.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /eventsWithMetadata:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return Accessible Events with Metadata
      operationId: Events_GetEventsWithMetadata
      parameters:
      - name: from
        in: query
        required: true
        description: 'Start of a time range supplied in dateOption parameter. Format must be compliant with ISO8601 and expressed in UTC format. Maximum precision is down to the second. (Example: 2021-03-16T16:19:58).'
        schema:
          type: string
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d
          nullable: false
        x-position: 1
      - name: to
        in: query
        required: true
        description: 'End of a time range supplied in dateOption parameter. Format must be compliant with ISO8601 and expressed in UTC format. Maximum precision is down to the second. (Example: 2021-03-16T16:19:58).'
        schema:
          type: string
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d
          nullable: false
        x-position: 2
      - name: dateOption
        in: query
        description: Date range option (lastUpdatedDate, recordDate). By default service will return the latest events.
        schema:
          type: string
          default: lastUpdatedDate
          nullable: true
        x-position: 3
      - name: groupId
        in: query
        description: Id of the group of the events of interest. If the group does not exist or is not visible to the user due to security then no results will be returned. If not supplied, then events in all groups accessible to the group of encompassed access key will be returned (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 4
      - name: triggers
        in: query
        style: form
        explode: true
        description: Ids of triggers of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 5
      - name: statuses
        in: query
        style: form
        explode: true
        description: Ids of statuses of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 6
      - name: behaviors
        in: query
        style: form
        explode: true
        description: Ids of behaviors of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 7
      - name: driverId
        in: query
        description: Id of a driver associated to the event (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 8
      - name: vehicleId
        in: query
        description: Id of a vehicle associated to the event (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 9
      - name: deviceId
        in: query
        description: Id of a device associated to the event.
        schema:
          type: string
          maxLength: 50
          minLength: 0
          nullable: true
        x-position: 10
      - name: sortDirection
        in: query
        description: Type of sorting direction (asc or desc). By default the service will return items in descending order.
        schema:
          type: string
          default: desc
          nullable: true
        x-position: 11
      - name: sortBy
        in: query
        description: A value to sort by (lastUpdatedDate, recordDate). By deafult the service will return items sorted by last updated date.
        schema:
          type: string
          default: lastUpdatedDate
          nullable: true
        x-position: 12
      - name: includeSubgroups
        in: query
        description: Indicates whether results should include data for all subgroups of the group specified. Default to true.
        schema:
          type: boolean
          default: true
        x-position: 13
      - name: limit
        in: query
        description: 'Indicates count of items to retrieve. By default the service will return 1000 items. Range: [1, 1000]'
        schema:
          type: integer
          format: int32
          default: 1000
          maximum: 1000
          minimum: 1
        x-position: 14
      - name: page
        in: query
        description: "Number of the page of event records to be returned.\r\n            If not provided, first page of records will be returned."
        schema:
          type: integer
          format: int32
          maximum: 2147483647
          minimum: 1
        x-position: 15
      responses:
        '200':
          description: Events retrieved with metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEvent'
        '204':
          description: No events were found that match the specified selection criteria.
        '400':
          description: The parameters given in the request are invalid.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return Accessible Events IDs
      operationId: Events_GetEvents
      parameters:
      - name: from
        in: query
        description: 'Start of a time range supplied in dateOption parameter. If not provided the latest events will be retrieved. Format must be compliant with ISO8601 and expressed in UTC format. Maximum precision is down to the second. (Example: 2021-03-16T16:19:58).'
        schema:
          type: string
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d
          nullable: true
        x-position: 1
      - name: to
        in: query
        description: 'End of a time range supplied in dateOption parameter. If not provided the latest events will be retrieved. Format must be compliant with ISO8601 and expressed in UTC format. Maximum precision is down to the second. (Example: 2021-03-16T16:19:58).'
        schema:
          type: string
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d
          nullable: true
        x-position: 2
      - name: dateOption
        in: query
        description: Date range option (lastUpdatedDate, recordDate). By default service will return the latest events.
        schema:
          type: string
          default: lastUpdatedDate
          nullable: true
        x-position: 3
      - name: groupId
        in: query
        description: Id of the group of the events of interest. If the group does not exist or is not visible to the user due to security then no results will be returned. If not supplied, then events in all groups accessible to the group of encompassed access key will be returned (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 4
      - name: triggers
        in: query
        style: form
        explode: true
        description: Ids of triggers of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
      - name: triggerSubTypes
        in: query
        style: form
        explode: true
        description: Ids of subtriggers of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 5
      - name: statuses
        in: query
        style: form
        explode: true
        description: Ids of statuses of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 6
      - name: behaviors
        in: query
        style: form
        explode: true
        description: Ids of behaviors of events to be filtered.
        schema:
          type: array
          nullable: true
          items:
            type: integer
        x-position: 7
      - name: driverId
        in: query
        description: Id of a driver associated to the event (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 8
      - name: vehicleId
        in: query
        description: Id of a vehicle associated to the event (GUID).
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 9
      - name: deviceId
        in: query
        description: Id of a device associated to the event.
        schema:
          type: string
          maxLength: 50
          minLength: 0
          nullable: true
        x-position: 10
      - name: sortDirection
        in: query
        description: Type of sorting direction (asc or desc). By default the service will return items in descending order.
        schema:
          type: string
          default: desc
          nullable: true
        x-position: 11
      - name: sortBy
        in: query
        description: A value to sort by (lastUpdatedDate, recordDate). By deafult the service will return items sorted by last updated date.
        schema:
          type: string
          default: lastUpdatedDate
          nullable: true
        x-position: 12
      - name: includeSubgroups
        in: query
        description: Indicates whether results should include data for all subgroups of the group specified. Default to true.
        schema:
          type: boolean
          default: true
        x-position: 13
      - name: limit
        in: query
        description: 'Indicates count of items to retrieve. By default the service will return 1000 items. Range: [1, 1000]'
        schema:
          type: integer
          format: int32
          default: 1000
          maximum: 1000
          minimum: 1
        x-position: 14
      - name: page
        in: query
        description: "Number of the page of event records to be returned.\n            If not provided, first page of records will be returned."
        schema:
          type: integer
          format: int32
          maximum: 2147483647
          minimum: 1
        x-position: 15
      responses:
        '200':
          description: Events retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafetyEvents'
        '204':
          description: No events were found that match the specified selection criteria.
        '400':
          description: The parameters given in the request are invalid.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/statuses:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return List of Possible Event Statuses
      operationId: Events_GetEventStatuses
      responses:
        '200':
          description: Event statuses retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEventStatus'
        '204':
          description: No event statuses found.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/behaviors:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return List of Possible Event Behaviors
      operationId: Events_GetEventBehaviors
      responses:
        '200':
          description: Event behaviors retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEventBehavior'
        '204':
          description: No event behaviors found.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/dynamicRisks:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return List of Possible Dynamic Risks
      operationId: Events_GetDynamicRisk
      responses:
        '200':
          description: Event dynamic risks retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEventDynamicRisks'
        '204':
          description: No dynamic risks found.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/{eventId}/file:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return Event File for Specified Event in Specified File format
      operationId: Events_GetEventFile
      parameters:
      - name: eventId
        in: path
        required: true
        description: Id of the event of interest.
        schema:
          type: string
          pattern: ^[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}$
          nullable: true
        x-position: 1
      - name: format
        in: query
        required: true
        description: Format of the wanted file (dce or mp4).
        schema:
          type: string
          nullable: true
        x-position: 2
      responses:
        '200':
          description: File retrieved.
          content:
            application/octet-stream:
              schema:
                type: string
                format: byte
            video/mp4:
              schema:
                type: string
                format: byte
        '400':
          description: The parameters given in the request are invalid.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions. In order to enable video file downloads, contact lytx team.
        '404':
          description: File does not exist.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/triggersubtypes:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return List of Possible Event Trigger Subtypes
      operationId: Events_GetEventTriggerSubtype
      responses:
        '200':
          description: Event trigger subtype retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafetyEventTriggerSubtype'
        '204':
          description: No event trigger subtype found.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
  /events/{id}:
    get:
      tags:
      - Safety Events (DriveCam)
      security:
      - bearerAuth: []
      summary: Return Specified Event
      operationId: Events_GetEventById
      parameters:
      - name: id
        in: path
        required: true
        description: ID or Customer specific ID of the event of interest. The parameter depends on idOption parameter
        schema:
          type: string
          nullable: true
        x-position: 1
      responses:
        '200':
          description: Event retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SafetyEvent'
        '400':
          description: The parameters given in the request are invalid.
        '401':
          description: Unauthorized due to providing an invalid access key, or invalid pod.
        '403':
          description: Access is forbidden. The given API access-key does not have the required permissions.
        '404':
          description: Event does not exist.
        '500':
          description: Internal server error
        '503':
          description: Database is unavailable.
components:
  schemas:
    SafetyEvent:
      type: object
      additionalProperties: false
      required:
      - id
      - customerEventId
      - eventTriggerId
      - eventTriggerSubTypeId
      - eventStatusId
      - recordDateUTC
      - recordDateTZ
      - recordDateUTCOffset
      - score
      - erSerialNumber
      - groupId
      - creationDate
      - objectRevision
      properties:
        id:
          type: string
          description: Unique ID for the event in the system.
          format: guid
          minLength: 1
        customerEventId:
          type: string
          description: Unique ID for the event within the customer’s data(not unique across customers).
          minLength: 1
        eventTriggerId:
          type: integer
          description: ID of the event trigger.
        eventTriggerSubTypeId:
          type: integer
          description: ID of the event trigger subtype.
        eventStatusId:
          type: integer
          description: ID of the event status.
        recordDateUTC:
          type: string
          description: Date event was recorded in UTC.
          format: date-time
          minLength: 1
        recordDateTZ:
          type: string
          description: 3-4 letter abbreviation of time zone associated with ER at time event was recorded.
          minLength: 1
        recordDateUTCOffset:
          type: integer
          description: Offset in minutes including sign from UTC time at which event was recorded.
          format: int32
        downloadedDate:
          type: string
          description: Date event was downloaded from the ER in UTC, may be null.
          format: date-time
          nullable: true
        score:
          type: integer
          description: Event’s risk score.
          format: int32
        reviewedDate:
          type: string
          description: Date event was reviewed in UTC, may be null if event hasn't been reviewed.
          format: date-time
          nullable: true
        erSerialNumber:
          type: string
          description: Serial number of the ER that captured the event.
          minLength: 1
        overDue:
          type: number
          description: Number of days that the event is overdue (forreviewing/coaching), may be null.
          format: decimal
          nullable: true
        vehicleId:
          type: string
          description: ID of the vehicle associated to the ER that captured the event, may be null if no vehicle is associated with the event.
          format: guid
          nullable: true
        groupId:
          type: string
          description: ID of the group that the event is associated to.
          format: guid
          minLength: 1
        forwardMax:
          type: number
          description: Maximum forward g-force that occurred within the event, may be null.
          format: decimal
          nullable: true
        lateralMax:
          type: number
          description: Maximum lateral g-force that occurred within the event, may be null.
          format: decimal
          nullable: true
        forwardThreshold:
          type: number
          description: Forward g-force threshold that ER was configured for at the time event was captured, may be null.
          format: decimal
          nullable: true
        lateralThreshold:
          type: number
          description: Lateral g-force threshold that ER was configured for at the time event was captured, may be null.
          format: decimal
          nullable: true
        shockThreshold:
          type: number
          description: Shock g-force threshold that ER was configured for at the time event was captured, may be null.
          format: decimal
          nullable: true
        speed:
          type: number
          description: Speed at time of trigger in meters per second, may be null if no speed data is available at the trigger.
          format: double
          nullable: true
        latitude:
          type: number
          description: Latitude at time of trigger, may be null if no latitude data is available at the trigger.
          format: decimal
          nullable: true
        longitude:
          type: number
          description: Longitude at time of trigger, may be null if no longitude data is available at the trigger.
          format: decimal
          nullable: true
        heading:
          type: number
          description: Heading (direction) at time of trigger, may be null if no heading data is available at the trigger.
          format: decimal
          nullable: true
        driverId:
          type: string
          description: ID of the driver associated with this event, may be null if no driver is associated with the event.
          format: guid
          nullable: true
        coachId:
          type: string
          description: ID of the coach associated with this event, may be null if no coach is associated with the event.
          format: guid
          nullable: true
        coachedDate:
          type: string
          description: Date when driver associated to the event was coached in UTC, may be null.
          format: date-time
          nullable: true
        creationDate:
          type: string
          description: Timestamp when event was created in the system.
          format: date-time
          minLength: 1
        notes:
          type: array
          description: Notes written up for this event (by reviewer, coach, and/or driver).
          nullable: true
          items:
            $ref: '#/components/schemas/Note'
        eventNotes:
          type: array
          description: EventNotes written up for this event
          nullable: true
          items:
            $ref: '#/components/schemas/Note'
        coachingSessionNotes:
          type: array
          description: CoachingSessionNotes written up for this event
          nullable: true
          items:
            $ref: '#/components/schemas/Note'
        reviewNotes:
          type: array
          description: ReviewNotes written up for this event
          nullable: true
          items:
            $ref: '#/components/schemas/Note'
        behaviors:
          type: array
          description: List of behaviors currently associated with the event,
          nullable: true
          items:
            $ref: '#/components/schemas/SafetyEventBehavior'
        dynamicRisks:
          type: array
          description: List of dynamic risks currently associated with the event,
          nullable: true
          items:
            $ref: '#/components/schemas/SafetyEventDynamicRisks'
        objectRevision:
          type: integer
          description: Revision number of the event at time data is retrieved.
          format: int32
        revisionDate:
          type: string
          description: Timestamp of last revision of the object, may be null if event hasn’t changed since it was created.
          format: date-time
          nullable: true
        coachingOverdueDate:
          type: string
          description: The date when the event becomes overdue for coaching.
          format: date-time
          nullable: true
        coachEmployeeNum:
          type: string
          description: Employee Number of the coach associated with this event, may be null if no coach is associated with the event.
        coachFirstName:
          type: string
          description: First Name of the coach associated with this event, may be null if no coach is associated with the event.
        coachLastName:
          type: string
          description: Last Name of the coach associated with this event, may be null if no coach is associated with the event.
        driverEmployeeNum:
          type: string
          description: Employee Number of the driver associated with this event, may be null if no driver is associated with the event.
        driverFirstName:
          type: string
          description: First Name of the driver associated with this event, may be null if no driver is associated with the event.
        driverLastName:
          type: string
          description: Last Name of the driver associated with this event, may be null if no driver is associated with the event.
        isCoachable:
          type: boolean
          description: Determines if the event is coachable or not.
    SafetyEvents:
      type: object
      additionalProperties: false
      required:
      - totalCount
      - eventsIds
      properties:
        totalCount:
          type: integer
          description: Total count of event ids.
          format: int64
        eventsIds:
          type: array
          description: Collection of events IDs.
          items:
            type: string
            format: guid
    SafetyEventStatus:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - creationDate
      properties:
        id:
          type: integer
          description: Unique id of the status.
          format: int32
        name:
          type: string
          description: Name of the status.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of the status.
          format: date-time
          minLength: 1
    Note:
      type: object
      additionalProperties: false
      required:
      - id
      - body
      - creationDate
      - authorUserId
      - firstName
      - lastName
      properties:
        id:
          type: string
          description: Id of note.
          format: guid
          minLength: 1
        body:
          type: string
          description: Content of note.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of note.
          format: date-time
          minLength: 1
        authorUserId:
          type: string
          description: Id of author.
          format: guid
          minLength: 1
        firstName:
          type: string
          description: First name of author.
          minLength: 1
        lastName:
          type: string
          description: Last name of author.
          minLength: 1
    SafetyEventDynamicRisks:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - creationDate
      properties:
        id:
          type: integer
          description: Unique id of the dynamic risk.
          format: int32
        name:
          type: string
          description: Name of the dynamic risk.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of the dynamic risk.
          format: date-time
          minLength: 1
    SafetyEventBehavior:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - creationDate
      properties:
        id:
          type: integer
          description: Unique id of the behavior.
          format: int32
        name:
          type: string
          description: Name of the behavior.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of the behavior.
          format: date-time
          minLength: 1
    SafetyEventTrigger:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - creationDate
      properties:
        id:
          type: integer
          description: Unique id of the trigger.
          format: int32
        name:
          type: string
          description: Name of the trigger.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of the trigger.
          format: date-time
          minLength: 1
    SafetyEventTriggerSubtype:
      type: object
      additionalProperties: false
      required:
      - id
      - name
      - creationDate
      properties:
        id:
          type: integer
          description: Unique id of the trigger subtype.
          format: int32
        name:
          type: string
          description: Name of the trigger subtype.
          minLength: 1
        creationDate:
          type: string
          description: Creation date of the trigger subtype.
          format: date-time
          minLength: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer