How Versioning Works

Samsara creates a new API version whenever there are backwards incompatible changes to our API. See below for what is considered a backward incompatible change versus a backward compatible change. Our versions follow a date format, where each new version is marked by a day, month, and year (e.g. 2020-06-15). Key highlights:

• API versions are unique for each API token
• When brand new endpoints are released, they can be called by all existing API versions by default
• Integrations using OAuth 2.0 will always default to the access_token using the latest API version, unless the version is explicitly defined in the header (see below)
• API versions apply to our [Open Beta] Event Subscriptions feature as well. Please share any feedback here.

Changing API Versions

There are two ways API Versions can be changed for an API token. When changing the API version, be sure you have handled for any breaking changes that come with that API version, otherwise you integration could break.

Upgrade Version in the Dashboard

❗️

This option only applies to the API Token authentication method, not the OAuth 2.0 authentication method

API versions can be viewed and upgraded in the dashboard's "API Token" page. Note that you can't set any arbitrary version, you can only upgrade existing API tokens on old API versions to the most current API Version:

Changing Version in the HTTP Header

API versions can be changed or overrode by providing an X-Samsara-Version HTTP header with your request. We recommend always passing in this header value for you API requests as a way to confirm your integration's API requests are using the version of the API you designed your integration with.

Here is an example:

X-Samsara-Version: 2018-01-01
Authorization: Bearer <token>

Backwards Incompatible Changes

Samsara versions the API for any of the following types of changes:

• adding required request body fields, request body field values, or query params
• removing allowed request body fields, request body field values, query params, or query param values
• reducing documented rate limits per endpoint, per token, or per org
• renaming request/response body fields, request body field values, query params, query param values
• renaming or removing valid values for enumerated fields (e.g. all different options for type of safety event)
• changing error codes
• changing the data type of a field (e.g. from string to int)
• changing the nested JSON shape of requests/responses
• changing the expected payload of a response (e.g. returning active and inactive drivers versus just active)
• deprecating access to certain endpoints

Backwards Compatible Changes

Samsara does not version the API for the following types of changes. The following list is not exhaustive and is used for explaining the most common non-breaking changes:

• changing the error message of an API endpoint's error
• changing the structure of a field's string value returned in a response body