Versioning

📘

API Changelog

See the API changelog for all API updates!

📘

Subscribe to API Updates

You can get sign up to get emails whenever a new API changelog post is made! Check out this page for details!

You can also sign up for a quarterly Developer Newsletter here!

When backwards-incompatible changes are made to the API, a new, dated version is released (e.g. 2020-06-15).

Examples of backwards-incompatible changes include:

  • Adding required request parameters or required request body fields to existing API methods
  • Removing properties from existing API responses

New features that are backwards-compatible will be available to all API versions. Examples of these include:

  • Adding new API resources
  • Adding optional request parameters or optional request body fields to existing API methods
  • Adding new properties to existing API responses
  • Changing the order of properties in existing API responses
  • Changing the length or format of object IDs or other opaque strings
  • Adding to the list of valid values for enum fields in API responses (e.g., adding more values to the list of valid values for the safety events label field)

📘

Tip

Because Samsara reserves the right to add to the list of valid values for enum fields, you should always provide a default case when handling these fields. For example, the following Python code provides a default case when handling the safety events label enum field:

if label == 'crash':
    # handle crash events
elif label == 'harshTurn':
    # handle harsh turn events
# ... handle other types of labels
else:
    # handle unknown labels

Requests will use the version associated with your API token unless you override it in the HTTP header.

You can view the versions associated with your API tokens in the dashboard by going to the API tokens section of the Settings page.

Cloud Dashboard -> Settings -> API TokensCloud Dashboard -> Settings -> API Tokens

Cloud Dashboard -> Settings -> API Tokens

You can update a token's version by clicking the "Update" link next to the version.

Version HTTP Header

You can override the version of your API token by providing an X-Samsara-Version HTTP header with your request:

GET /fleet/vehicles/locations HTTP/1.1
Host: api.samsara.com
X-Samsara-Version: 2018-01-01
Authorization: Bearer <token>

The above will override the request to use the 2018-01-01 version of the endpoint regardless of the version the API token is associated with.


What’s Next
Did this page help you?