Docs Menu
Docs Home
MongoDB Atlas
/ /

Versioned Atlas Administration API Overview

On this page

  • Benefits of the Versioned Atlas Administration API
  • Versioning Schema
  • Next Steps

Atlas provides versioned Atlas Administration API for a predictable and consistent experience when handling API changes. The API versioning happens at the individual API resource-level. So, you need to take action if and when Atlas deprecates the resources that you are utilizing. You don't need to take any action if you haven't implemented a resource for which Atlas released a new version. This allows you to plan for new features, prevent breaking changes, and ensure a smooth integration process while maintaining stability and minimizing disruptions in your production environment.

The new versioned Atlas Administration API gives a significantly better overall experience in accessing Atlas programmatically. The versioned Atlas Administration API provides the following:

Atlas introduces all new feature with breaking changes in a new resource version. Features that contain non-breaking changes will continue to be added to the current, stable resource version. When Atlas introduces a new resource version, you can continue to use the current stable resource version until it is fully deprecated while you develop and test on the new API resource version.

Atlas deprecates and then removes resource versions only when it introduces a new stable API resource version. Atlas will continue to support the older resource version for use in your production environment for up to twelve months, which provides you with time to plan and execute your migration to the next version.

Starting with the new Versioned Atlas Administration API (v2), Atlas Administration API version is based on the lifecycle of the Atlas Administration API resource.

Starting in Versioned Atlas Administration API (v2), Atlas Administration API endpoints go through the stable, deprecated, and sunset stages in the lifecycle.


The stages only apply to Atlas Administration API endpoints in Versioned Atlas Administration API (v2) of the resource. These stages don't affect Atlas Administration API endpoints in resource v1.0 or v1.5. Atlas exposes all legacy (v1.0 and v1.5) Atlas Administration API resources in its first release on 2023-02-01 in stable state.


Atlas supports stable endpoints for use in production environments. Atlas provides documentation, with changelogs, for all stable endpoints. Resource version in this state will only be updated with non-breaking changes.

When Atlas introduces breaking changes to endpoints, it creates a new resource version. When a new resource version is released, Atlas also automatically deprecates the current stable version of that resource. Atlas exposes all legacy (v1.0 and v1.5) Atlas Administration API resources in its first release on 2023-02-01 in stable state. Atlas will support the first release (2023-01-01 and 2023-02-01) of the versioned Atlas Administration API for 24 months after its deprecation. Note that the /clusters resource version 2023-01-01 (and equivalent of /v1.0/clusters) resource is marked as deprecated with two years deprecation window.

To use Atlas Administration APIs in this state, send a request to the resource and include the following as the HTTP Accept header:

Accept: application/vnd.atlas.<yyyy-mm-dd>+json

where the value for <yyyy-mm-dd> is the release date of the endpoint as listed in the documentation and the changelog.

Atlas returns 406 Not Acceptable error response code if your request omits or specifies a resource version that doesn't exist in the header.


Atlas automatically deprecates a resource version when Atlas introduces a new, stable resource version. Atlas releases a new, stable version when it introduces breaking changes to an existing resource.

Atlas notifies you about deprecated resource versions in the response header for requests. Atlas will support the first releases of the Atlas Administration API (2023-01-01 and 2023-02-01) for twenty-four months after deprecation. Subsequently, Atlas supports any future deprecated resource versions for use in your production environment for twelve months before automatically removing them.


The following shows an example response header for a request to a deprecated resource scheduled for removal in the future.

Deprecation: Wed, 1 Feb 2023 00:00:00 GMT
Sunset: Sun, 1 Jun 2025 00:00:00 GMT

You can continue to send requests to older resource versions of the endpoint until they are removed. However, you should migrate to the latest resource version as soon as possible to mitigate disruptions when older resource versions are removed. To learn more about migrating to a new resource version, see Migrate to the New Versioned Atlas Administration API.


Atlas automatically removes resource versions after one year of deprecation. If you send a request to a removed resource version, Atlas returns the 410 Gone error response code.


The following example illustrates the lifecycle of a resource and its impact on versioning.

Illustration of admin API versioning lifecycle

The preceding illustration shows the following:

Release Date
Release Details
API Lifecyle
First release of a resource in the Versioned API. It has a deprecation period of 12 months.
  • #stable: application/vnd.atlas.2023-06-01+json

  • #deprecated: None

  • #sunset: None

New resource version created, older versions are automatically deprecated.
  • #stable: application/vnd.atlas.2024-06-01+json

  • #deprecated: application/vnd.atlas.2023-06-01+json

  • #sunset: None

New stable version created, with short sunset
  • #stable: application/vnd.atlas.2025-01-01+json

  • #deprecated:

    • application/vnd.atlas.2024-12-01~preview+json

    • application/vnd.atlas.2024-06-01+json

  • #sunset: application/vnd.atlas.2023-06-01+json

For legacy unversioned Atlas Administration API endpoints, Atlas introduced new and breaking changes in the same version. Starting in versioned Atlas Administration API (v2), Atlas introduces breaking changes only in a new resurce version. Atlas will continue to introduce non-breaking changes to existing stable version. Use the release date of a resource to submit a request to a specific version of a versioned Atlas Administration API (v2) endpoint.

The following table shows the legacy API endpoint versions, whether the version has a corresponding versioned Atlas Administration API (v2) endpoint, and the release date of the versioned Atlas Administration API (v2) resource. Note that an equivalent of v1.0 in the unversioned Atlas Administration API is represented by 2023-01-01 in the versioned Atlas Administration API, which is now deprecated.

Version Number
Supported in v2?
v2 Resource Version (in yyyy-mm-dd format)
  1. Review the API changelog, which gives you visibility into all API changes across different versions.

  2. Review the API Specification, which contains information for all stable and deprecated resource versions.

  3. Follow the steps in the Migration Guide to migrate from the current unversioned Atlas Administration API to the new versioned Atlas Administration API.

← Atlas Administration API Authentication