Samsara Maintenance API
The Maintenance API from Samsara — 3 operation(s) for maintenance.
OpenAPI Specification
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