In Fall of 2019, Samsara released a new generation of API endpoints. This new generation currently coexists with our "v1" generation, but we are actively reimplementing all our legacy "v1" endpoints on this new standard. Read on to learn about what's new with this new generation and what it means for your existing applications.

What's new with this API?

In reviewing feedback on the first generation of our API, we set our sights on standardizing our API and making it easier to use. Here are some of the new API standards you can look forward to:

Pagination across endpoints
Human-readable timestamps (RFC 3339 strings)
Nested objects
Standard naming conventions and consistent RESTful practices
More accurate and consistent error codes
More options for how to consume time-series data

What does this mean for me?

Instead of introducing breaking changes to existing endpoints, we're releasing brand-new endpoints with the above improvements.

This allows you to take advantage of new endpoints on a case-by-case basis rather than having to upgrade an existing application all at once.

All new endpoints will lack the /v1/ prefix in the endpoint URL. Samsara will be building out all new API features on this new standard.

The new endpoints are available to all API access tokens on any version, so you can use legacy endpoints and new endpoints together in the same application.

How do I use this new API?

All you need is an API token. You can use any Samsara API token, new or existing, to make a call to these new endpoints. You can use the same API token to call both legacy endpoints as well as the new endpoints we're releasing.

Note: These new APIs require that you pass in the API token using the HTTP Authorization header, rather than passing it in as a query parameter.

Root URL

The root URL for this new API:

https://api.samsara.com/<endpoint> or https://api.eu.samsara.com/<endpoint> (for EU customers)

The root URL for legacy endpoints (note the v1 prefix):

https://api.samsara.com/v1/<endpoint> or https://api.eu.samsara.com/v1/<endpoint> (for EU customers)

Because the new API and the legacy API have different root URLs, this allows you to take advantage of both using the same API token.

Versioning

Samsara versions the API if we need to introduce any breaking changes. Versions are tied to your API access token.

The new APIs are available to all token versions. If a breaking change is necessary for either API (legacy or new), we'll release a dated-version. You can choose to upgrade your token to that version at any time, but both sets of APIs (old and new) will always be available to all versions.

You can read more about versioned tokens here.

Permissions

You can have full-access or read-only API tokens. Any permissions level on an API token will apply to both sets of APIs.

What's going to happen to the legacy API?

Applications built on the legacy API will continue to operate normally, and we currently do not have any plans to discontinue support for the legacy API. However, we do encourage you to take a look at this new set of endpoints, as we'll be transitioning all legacy endpoints to these new standards. New feature development will also occur on this new API standard.

You can still access the legacy API documentation here.

Should I migrate my code?

We do not require customers to migrate code, but we encourage you to explore this new API and consider transitioning over as more endpoints on these new standards become available. We will do all new feature development using this new API structure.

When migrating your code over, please note that the new API no longer has the /v1 prefix, and there have been some naming changes.

Feedback

Feedback or questions? Feel free to submit this quick form.