openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Maintenance API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Maintenance
paths:
  /fleet/defects/history:
    get:
      description: "Returns a list of DVIR defects in an organization, filtered by creation time. The maximum time period you can query for is 30 days. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Defects** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: getDvirDefects
      parameters:
      - description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
        in: query
        name: limit
        schema:
          format: int64
          maximum: 512
          minimum: 1
          type: integer
      - description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
        in: query
        name: after
        schema:
          type: string
      - description: 'A start time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00). *The maximum time period you can query for is 30 days.*'
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: 'An end time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00). *The maximum time period you can query for is 30 days.*'
        in: query
        name: endTime
        required: true
        schema:
          type: string
      - description: 'A filter on the data based on resolution status. Example: `isResolved=true`'
        in: query
        name: isResolved
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefectsResponse'
          description: List of all DVIR defects in the organization
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standardErrorResponse'
          description: Error response
      summary: Get All Defects
      tags:
      - Maintenance
  /fleet/dvirs/history:
    get:
      description: "Returns a list of all DVIRs in an organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: getDvirHistory
      parameters:
      - description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
        in: query
        name: limit
        schema:
          format: int64
          maximum: 512
          minimum: 1
          type: integer
      - description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
        in: query
        name: after
        schema:
          type: string
      - description: 'A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
        explode: false
        in: query
        name: parentTagIds
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
        explode: false
        in: query
        name: tagIds
        schema:
          items:
            type: string
          type: array
        style: form
      - description: 'A start time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: startTime
        required: true
        schema:
          type: string
      - description: 'An end time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
        in: query
        name: endTime
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DvirsListResponse'
          description: List of all DVIRs in the organization
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standardErrorResponse'
          description: Error response
      summary: Get All DVIRs
      tags:
      - Maintenance
  /v1/fleet/maintenance/list:
    get:
      description: "<n class=\"warning\">\n<nh>\n<i class=\"fa fa-exclamation-circle\"></i>\nThis endpoint is still on our legacy API.\n</nh>\n</n>\n\nGet list of the vehicles with any engine faults or check light data. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read DVIRs** under the Maintenance category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
      operationId: V1getFleetMaintenanceList
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_4'
          description: List of vehicles and maintenance information about each.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ErrorResponse'
          description: Unexpected error.
      summary: Get Vehicles With Engine Faults or Check Lights
      tags:
      - Maintenance
components:
  schemas:
    V1VehicleMaintenance_j1939:
      description: J1939 based data. Null if no data is available.
      properties:
        checkEngineLight:
          $ref: '#/components/schemas/V1VehicleMaintenance_j1939_checkEngineLight'
        diagnosticTroubleCodes:
          description: J1939 DTCs.
          items:
            $ref: '#/components/schemas/V1VehicleMaintenance_j1939_diagnosticTroubleCodes'
          type: array
      type: object
    DvirsListResponse:
      description: A list of DVIRs and pagination information.
      properties:
        data:
          description: A list of DVIRs.
          items:
            $ref: '#/components/schemas/Dvir'
          type: array
        pagination:
          $ref: '#/components/schemas/paginationResponse'
      required:
      - data
      - pagination
      type: object
    DvirVehicle:
      allOf:
      - description: The vehicle the DVIR was submitted for. Only included for tractor or tractor+trailer DVIRs.
        type: object
      - $ref: '#/components/schemas/vehicleTinyResponse'
    V1VehicleMaintenance_j1939_diagnosticTroubleCodes:
      properties:
        fmiId:
          type: integer
        fmiText:
          type: string
        occurrenceCount:
          type: integer
        spnDescription:
          type: string
        spnId:
          type: integer
        txId:
          type: integer
      required:
      - fmiId
      - fmiText
      - occurrenceCount
      - spnDescription
      - spnId
      - txId
      type: object
    V1ErrorResponse:
      description: Error message describing why the request failed.
      type: string
    DvirSignature:
      description: DVIR Signure.
      properties:
        signatoryUser:
          allOf:
          - description: The user who signed the DVIR.
            type: object
          - $ref: '#/components/schemas/userTinyResponse'
          type: object
        signedAtTime:
          description: 'The time when the DVIR was signed. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        type:
          default: driver
          description: 'Whether the DVIR was submitted by a `driver` or `mechanic`. Valid values: `driver`, `mechanic`.'
          enum:
          - driver
          - mechanic
          example: driver
          type: string
      type: object
    vehicleTinyResponse:
      description: A minified vehicle object.
      properties:
        ExternalIds:
          additionalProperties:
            type: string
          description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
          example:
            maintenanceId: '250020'
            payrollId: ABFS18600
          type: object
        id:
          description: ID of the vehicle.
          example: '123456789'
          type: string
        name:
          description: Name of the vehicle.
          example: 'Midwest Truck #4'
          type: string
      type: object
    DvirVehicleDefects:
      description: Defects registered for the vehicle which was part of the DVIR.
      items:
        $ref: '#/components/schemas/dvirTrailerDefectsItems'
      type: array
    standardErrorResponse:
      description: Error response
      properties:
        message:
          description: The message of the error.
          example: An error has occurred.
          type: string
        requestId:
          description: The ID of the request.
          example: 8916e1c1
          type: string
      type: object
    DefectsResponse:
      description: A list of defects.
      properties:
        data:
          items:
            $ref: '#/components/schemas/Defect'
          type: array
        pagination:
          $ref: '#/components/schemas/paginationResponse'
      type: object
    DvirTrailerDefects:
      description: Defects registered for the trailer which was part of the DVIR.
      items:
        $ref: '#/components/schemas/dvirTrailerDefectsItems'
      type: array
    V1VehicleMaintenance:
      description: Contains any J1939/Passenger engine light warnings and engine faults.
      properties:
        id:
          description: ID of the vehicle.
          example: 112
          format: int64
          type: integer
        j1939:
          $ref: '#/components/schemas/V1VehicleMaintenance_j1939'
        passenger:
          $ref: '#/components/schemas/V1VehicleMaintenance_passenger'
      required:
      - id
      type: object
    DvirSecondSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Second Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    DvirLicensePlate:
      description: The license plate of this vehicle.
      example: XHK1234
      maxLength: 12
      type: string
    dvirTrailerDefectsItems:
      properties:
        comment:
          description: Comment on the defect.
          example: Air Compressor not working
          type: string
        createdAtTime:
          description: 'Time when the defect was created. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        defectType:
          description: The type of DVIR defect.
          example: Air Compressor
          type: string
        id:
          description: ID of the defect.
          example: '18'
          type: string
        isResolved:
          description: Signifies if this defect is resolved.
          example: true
          type: boolean
        mechanicNotes:
          description: The mechanics notes on the defect.
          example: Extremely large oddly shaped hole in passenger side window.
          type: string
        mechanicNotesUpdatedAtTime:
          description: 'Time when mechanic notes were last updated. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedAtTime:
          description: 'Time when this defect was resolved. Will not be returned if the defect is unresolved. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedBy:
          $ref: '#/components/schemas/Defect_resolvedBy'
        trailer:
          allOf:
          - description: The trailer this defect was submitted for.
            type: object
          - description: A minified trailer object.
            properties:
              id:
                description: ID of the trailer.
                example: '123456789'
                type: string
              name:
                description: Name of the trailer.
                example: 'Midwest Trailer #5'
                type: string
            type: object
          type: object
        vehicle:
          allOf:
          - description: The vehicle this defect was submitted for.
            type: object
          - description: A minified vehicle object.
            properties:
              ExternalIds:
                additionalProperties:
                  type: string
                description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
                example:
                  maintenanceId: '250020'
                  payrollId: ABFS18600
                type: object
              id:
                description: ID of the vehicle.
                example: '123456789'
                type: string
              name:
                description: Name of the vehicle.
                example: 'Midwest Truck #4'
                type: string
            type: object
          type: object
      required:
      - id
      - isResolved
      type: object
      x-go-gen-location: models
    Defect_resolvedBy:
      description: The person who resolved this defect.  Will not be returned if the defect is unresolved.
      properties:
        id:
          description: ID of the entity that resolved this defect. If the defect was resolved by a driver, this will be a Samsara Driver ID. If the defect was resolved by a mechanic, this will be the Samsara Dashboard User ID of the mechanic.
          example: '11'
          type: string
        name:
          description: Name of the person who resolved this defect.
          example: Christopher 'The Handyman' Zhen
          type: string
        type:
          description: Indicates whether this defect was resolved by a `driver` or a `mechanic`.
          enum:
          - driver
          - mechanic
          type: string
      type: object
    userTinyResponse:
      description: A minified user object.
      properties:
        id:
          description: ID of the user.
          example: '88668'
          type: string
        name:
          description: Name of the user.
          example: Susan Bob
          type: string
      type: object
    trailerTinyResponse:
      description: A minified trailer object.
      properties:
        id:
          description: ID of the trailer.
          example: '123456789'
          type: string
        name:
          description: Name of the trailer.
          example: 'Midwest Trailer #5'
          type: string
      type: object
    DvirAuthorSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Author Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    V1VehicleMaintenance_j1939_checkEngineLight:
      description: J1939 check engine lights.
      properties:
        emissionsIsOn:
          type: boolean
        protectIsOn:
          type: boolean
        stopIsOn:
          type: boolean
        warningIsOn:
          type: boolean
      type: object
    DvirTrailer:
      allOf:
      - description: The trailer the DVIR was submitted for. Only included for trailer only DVIRs.
        type: object
      - $ref: '#/components/schemas/trailerTinyResponse'
    DvirOdometerMeters:
      description: The odometer reading in meters.
      example: 14010293
      type: integer
    DvirLocation:
      description: Optional string if your jurisdiction requires a location of the DVIR.
      example: 350 Rhode Island St Ste. 400S, San Francisco, CA 94103
      type: string
    DvirThirdSignature:
      allOf:
      - description: An author signature object which has a signatory mini object with the signed time. Third Signature.
        type: object
      - $ref: '#/components/schemas/DvirSignature'
    V1VehicleMaintenance_passenger:
      description: Passenger vehicle data. Null if no data is available.
      properties:
        checkEngineLight:
          $ref: '#/components/schemas/V1VehicleMaintenance_passenger_checkEngineLight'
        diagnosticTroubleCodes:
          description: Passenger vehicle DTCs.
          items:
            $ref: '#/components/schemas/V1VehicleMaintenance_passenger_diagnosticTroubleCodes'
          type: array
      type: object
    paginationResponse:
      description: Pagination parameters.
      properties:
        endCursor:
          description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
          example: MjkY
          format: string
          type: string
        hasNextPage:
          description: True if there are more pages of results immediately available after this endCursor.
          example: true
          type: boolean
      required:
      - endCursor
      - hasNextPage
      type: object
    Dvir:
      description: Information about a DVIR.
      properties:
        authorSignature:
          $ref: '#/components/schemas/DvirAuthorSignature'
        endTime:
          description: 'Time when driver signed and completed this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        id:
          description: Unique Samsara ID for the DVIR.
          example: '7107471'
          type: string
        licensePlate:
          $ref: '#/components/schemas/DvirLicensePlate'
        location:
          $ref: '#/components/schemas/DvirLocation'
        mechanicNotes:
          $ref: '#/components/schemas/DvirMechanicNotes'
        odometerMeters:
          $ref: '#/components/schemas/DvirOdometerMeters'
        safetyStatus:
          default: unsafe
          description: 'The condition of vehicle on which DVIR was done. Valid values: `safe`, `unsafe`, `resolved`.'
          enum:
          - safe
          - unsafe
          - resolved
          example: unsafe
          type: string
        secondSignature:
          $ref: '#/components/schemas/DvirSecondSignature'
        startTime:
          description: 'Time when driver began filling out this DVIR. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        thirdSignature:
          $ref: '#/components/schemas/DvirThirdSignature'
        trailer:
          $ref: '#/components/schemas/DvirTrailer'
        trailerDefects:
          $ref: '#/components/schemas/DvirTrailerDefects'
        trailerName:
          description: The name of the trailer the DVIR was submitted for.  Only included for tractor+trailer DVIRs.
          example: 'Midwest Trailer #5'
          type: string
        type:
          default: unspecified
          description: 'Inspection type of the DVIR. Valid values: `preTrip`, `postTrip`, `mechanic`, `unspecified`.'
          enum:
          - preTrip
          - postTrip
          - mechanic
          - unspecified
          example: preTrip
          type: string
        vehicle:
          $ref: '#/components/schemas/DvirVehicle'
        vehicleDefects:
          $ref: '#/components/schemas/DvirVehicleDefects'
      required:
      - id
      type: object
    V1VehicleMaintenance_passenger_checkEngineLight:
      description: Passenger vehicle check engine light.
      properties:
        isOn:
          type: boolean
      type: object
    Defect:
      properties:
        comment:
          description: Comment on the defect.
          example: Air Compressor not working
          type: string
        createdAtTime:
          description: 'Time when the defect was created. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        defectType:
          description: The type of DVIR defect.
          example: Air Compressor
          type: string
        id:
          description: ID of the defect.
          example: '18'
          type: string
        isResolved:
          description: Signifies if this defect is resolved.
          example: true
          type: boolean
        mechanicNotes:
          description: The mechanics notes on the defect.
          example: Extremely large oddly shaped hole in passenger side window.
          type: string
        mechanicNotesUpdatedAtTime:
          description: 'Time when mechanic notes were last updated. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedAtTime:
          description: 'Time when this defect was resolved. Will not be returned if the defect is unresolved. UTC timestamp in RFC 3339 format. Example: `2020-01-27T07:06:25Z`.'
          example: '2020-01-27T07:06:25Z'
          type: string
        resolvedBy:
          $ref: '#/components/schemas/Defect_resolvedBy'
        trailer:
          allOf:
          - description: The trailer this defect was submitted for.
            type: object
          - $ref: '#/components/schemas/trailerTinyResponse'
          type: object
        vehicle:
          allOf:
          - description: The vehicle this defect was submitted for.
            type: object
          - $ref: '#/components/schemas/vehicleTinyResponse'
          type: object
      required:
      - id
      - isResolved
      type: object
    DvirMechanicNotes:
      description: The mechanics notes on the DVIR.
      example: Replaced headlight on passenger side.
      type: string
    V1VehicleMaintenance_passenger_diagnosticTroubleCodes:
      properties:
        dtcDescription:
          type: string
        dtcId:
          type: integer
        dtcShortCode:
          type: string
      required:
      - dtcDescription
      - dtcId
      - dtcShortCode
      type: object
    inline_response_200_4:
      properties:
        vehicles:
          items:
            $ref: '#/components/schemas/V1VehicleMaintenance'
          type: array
      type: object
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true