• API >
• API Resources >
• Clusters >
• Create a Cluster

Create a Cluster

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Note

This feature is not available for M0 (Free Tier) clusters. For more information, see Atlas M0 (Free Tier) Limitations.

The Atlas API uses HTTP Digest Authentication. Provide your Atlas username and API key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

copy

POST /api/atlas/v1.0/groups/{GROUP-ID}/clusters

Request Path Parameters

Path Element	Required/Optional	Description
GROUP-ID	Required.	The unique identifier for the project in which to create the cluster. Each Atlas project supports up to 50 clusters. Please contact Atlas support for questions or assistance regarding the cluster limit. To contact support, select Support from the left-hand navigation bar of the Atlas UI.

Request Body Parameters

Name	Type	Description
autoScaling	document	Optional Contains the diskGBEnabled field which specifies whether to enable or disable disk auto-scaling.
autoScaling.diskGBEnabled	boolean	Specifies whether disk auto-scaling is enabled. The default is true. Set to true to enable disk auto-scaling. Set to false to disable disk auto-scaling. Note Disk auto-scaling is subject to limitations based on the maximum amount of RAM for the selected cluster tier and the oplog size. See Customize Your Storage for details.
backupEnabled	Boolean	Optional Default is false. Set to true to enable Atlas continuous backups for the cluster. Set to false to disable continuous backups for the cluster. Atlas deletes any stored snapshots. See the continuous backup Snapshot Schedule for more information. You cannot enable continuous backups if you have an existing cluster in the project with Cloud Provider Snapshots enabled.
biConnector	document	Optional Specify whether to enable/disable BI Connector for Atlas. The BI Connector for Atlas is only available for M10+ clusters. The biConnector document includes the following fields: enabled Set to true to enable BI Connector for Atlas. Set to false to disable BI Connector for Atlas. readPreference Set to "primary" to have BI Connector for Atlas read from the primary. Set to "secondary" to have BI Connector for Atlas read from a secondary member. Default
clusterType	string	Specifies the type of the cluster. Required for Global Clusters. Optional for replica sets and sharded clusters. REPLICASET - replica set SHARDED - sharded cluster GEOSHARDED - Global Cluster Note You cannot convert a sharded cluster deployment to a replica set deployment.
encryptionAtRestProvider	string	Specify AWS to enable Encryption at Rest using the Atlas project AWS Key Management System settings. The cluster must meet the following restrictions: providerSettings.providerName must be AWS or AZURE. providerSettings.instanceSizeName must be M10 or greater. clusterType must be REPLICASET. backupEnabled must be false or omitted. For complete documentation on Encryption at Rest restrictions, see Restrictions. You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest via AWS KMS.
name	string	The name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
mongoDBMajorVersion	string	The version of the cluster to deploy. Atlas supports the following MongoDB versions for M10+ clusters: [1] 3.4 3.6 You must set this value to 3.6 if providerSettings.instanceSizeName is either M2 or M5. Atlas always deploys the cluster with the latest stable release of the specified version. You can upgrade to a newer version of MongoDB when you modify a cluster.
numShards	integer	Optional Selects whether the cluster is a replica set or a sharded cluster. If this is set to 1, the cluster is a replica set. For more information on MongoDB replica sets, see Replication in the MongoDB manual. If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified. For more information on sharded clusters, see Sharding in the MongoDB manual. For details on how this setting affects costs, see Number of Servers. The possible values are 1 through 24. The default value is 1. Note Do not include in the request body for Global Clusters.
paused	boolean	Optional. A flag that indicates whether the cluster is paused or not. The default value is false. You cannot create a paused cluster. Either omit the field or explicitly set to false.
providerBackupEnabled	Boolean	If true, the cluster uses Cloud Provider Snapshots for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups. You cannot enable cloud provider snapshots if you have an existing cluster in the project with Continuous Backups enabled. If numShards is greater than 1, you cannot enable this option.
providerSettings	document	The configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.providerName	string	The cloud service provider on which the servers are provisioned. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure TENANT - A multi-tenant deployment on one of the supported cloud service providers. Only valid when providerSettings.instanceSizeName is either M2 or M5. Important M2 and M5 instance sizes are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.
providerSettings.backingProviderName	string	The cloud service provider on which the server for a multi-tenant cluster is provisioned. This setting is only valid when providerSetting.providerName is TENANT and providerSetting.instanceSizeName is M2 or M5. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure
providerSettings.regionName	string	The physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases. Do not specify this field when creating a multi-region cluster using the replicationSpec document or a Global Cluster with the replicationSpecs array. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections. Important MongoDB does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC. The following regions are valid for M10+ clusters (M20+ for Azure): Provider Region Names AWS US_EAST_1 US_EAST_2 US_WEST_1 US_WEST_2 CA_CENTRAL_1 EU_WEST_1 EU_WEST_2 EU_WEST_3 EU_CENTRAL_1 AP_NORTHEAST_1 AP_NORTHEAST_2 AP_SOUTHEAST_1 AP_SOUTHEAST_2 AP_SOUTH_1 SA_EAST_1 GCP Note EASTERN_US corresponds to the GCP us_east_1 region. EASTERN_US US_EAST_4 CENTRAL_US WESTERN_US NORTH_AMERICA_NORTHEAST_1 SOUTH_AMERICA_EAST_1 WESTERN_EUROPE EUROPE_WEST_2 EUROPE_WEST_3 EUROPE_WEST_4 EASTERN_ASIA_PACIFIC NORTHEASTERN_ASIA_PACIFIC SOUTHEASTERN_ASIA_PACIFIC ASIA_SOUTH_1 AUSTRALIA_SOUTHEAST_1 AZURE US_CENTRAL US_EAST US_EAST_2 US_NORTH_CENTRAL US_WEST US_SOUTH_CENTRAL EUROPE_NORTH EUROPE_WEST FRANCE_CENTRAL US_WEST_2 CANADA_EAST CANADA_CENTRAL BRAZIL_SOUTH AUSTRALIA_EAST AUSTRALIA_SOUTH_EAST UK_SOUTH UK_WEST INDIA_CENTRAL INDIA_WEST INDIA_SOUTH ASIA_EAST JAPAN_EAST JAPAN_WEST ASIA_SOUTH_EAST KOREA_CENTRAL KOREA_SOUTH The following regions are valid for M2 and M5 clusters: Provider Region Names AWS US_EAST_1 US_WEST_2 EU_WEST_1 AP_SOUTHEAST_1 AP_SOUTHEAST_2 AP_SOUTH_1 GCP CENTRAL_US WESTERN_EUROPE EASTERN_ASIA_PACIFIC AZURE US_EAST_2 EUROPE_NORTH
providerSettings.instanceSizeName	string	Atlas provides different instance sizes, each with a default storage capacity and RAM size. The instance size you select is used for all the data-bearing servers in your cluster. For definitions of data-bearing servers, see Number of Servers. Atlas supports the following instance sizes. Atlas supports deploying M2 and M5 instances into a subset of available regions. The documentation for providersettings.regionName includes a list of these regions. Provider Instance Sizes AWS Instance Size Default Storage Default RAM M2 2GB Shared M5 5GB Shared M10 10GB 2GB M20 20GB 4GB M30 40GB 8GB M40 or R40 80GB 16GB M50 or R50 160GB 32GB M60 or R60 320GB 64GB R80 750GB 122GB M100 1TB 160GB M140 1 1TB 192GB M200 or R200 1.5TB 256GB M300 1 2TB 384GB R400 3TB 488GB 1 Only available if providerSettings.regionName is EU-WEST-3 (Paris). GCP Instance Size Default Storage Default RAM M2 2GB Shared M5 5GB Shared M10 10GB 1.70GB M20 20GB 3.75GB M30 40GB 7.5GB M40 80GB 15GB M50 160GB 30GB M60 320GB 60GB M80 750GB 120GB M200 1 1.5TB 240GB M300 1 2.2TB 360GB 1 Not available if providerSettings.regionName is SOUTH_AMERICA_EAST_1 , EUROPE_WEST_3, NORTHEASTERN_ASEA_PACIFIC, or AUSTRALIA_SOUTHEAST_1 AZURE Instance Size Default Storage Default RAM M2 2GB Shared M5 5GB Shared M20 32GB 3.5GB M30 32GB 7GB M40 128GB 14GB M50 128GB 28GB M60 128GB 56GB M90 128GB 140GB Important M2 and M5 instance sizes are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.
providerSettings.diskIOPS	integer	Optional AWS only Requires that providerSettings.instanceSizeName be M30 or greater. The maximum input/output operations per second (IOPS) the system can perform. The possible values depend on the selected providerSettings.instanceSizeName and diskSizeGB. To view the possible IOPS values for the selected instance size and storage capacity: Open the Atlas web interface. Select Build a New Cluster. Under Cloud Provider & Region, select AWS. Under Cloud Provider & Region, select the region corresponding to your configured providerSettings.regionName. Under Cluster Tier, select the instance size corresponding to your configured providerSettings.instanceSizeName. Under Cluster Tier, set the Storage Capacity slider to your configured diskSizeGB. Alternatively, input the exact value of diskSizeGB in the input box to the right of the slider. Atlas lists the possible IOPS values for the selected instance and storage size as Standard, Fast, and Fastest. Set the value of providerSettings.diskIOPS to your preferred IOPS setting. The default value for providerSettings.diskIOPS is the same as the instance size’s Standard IOPS value, as viewable in the Atlas interface. Changing this value affects the cost of running the cluster as described in the billing documentation.
providerSettings.diskTypeName	string	Optional Azure ONLY The Azure disk type of the server’s root volume. If ommitted, Atlas uses the default disk type for the selected providerSettings.instanceSizeName. The following table lists the possible values for this field, and their corresponding storage size. diskTypeName Storage Size P4 1 32GB P6 64GB P10 2 128GB P20 512GB P30 1024GB P40 2048GB P50 4095GB 1 Default for M20 and M30 Azure instances 2 Default for M40+ Azure instances
providerSettings.encryptEBSVolume	Boolean	Optional AWS only. If enabled, the Amazon EBS encryption feature encrypts the server’s root volume for both data at rest within the volume and for data moving between the volume and the instance. The default value is false.
replicationFactor	number	Optional The number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy. The possible values are 3, 5, or 7. The default value is 3. Do not specify this field when creating a multi-region cluster using the replicationSpec document. If your cluster is a sharded cluster, each shard is a replica set with the specified replication factor. For information on how the replication factor affects costs, see Number of Servers. For more information on MongoDB replica sets, see Replication in the MongoDB manual. Atlas ignores this value if you pass the replicationSpec document.
replicationSpec	document	Optional The configuration of each region in a multi-region cluster. Each element in this document represents a region where Atlas deploys your cluster. For single-region clusters, you can either specify the providerSettings.regionName and replicationFactor, or you can use the replicationSpec document to define a single region. For multi-region clusters, omit the providerSettings.regionName field. For Global Clusters, specify the replicationSpecs parameter rather than a replicationSpec parameter. Important You must order each element in this document by replicationSpec.<region>.priority descending. Use the replicationSpecs parameter to create a Global Cluster. Note You cannot specify both the replicationSpec and replicationSpecs parameters in the same request body.
replicationSpec.<region>	document	Required if specifying replicationSpec The physical location of the region. Replace <region> with the name of the region. Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region. You must order each <region> by replicationSpec.priority descending. You must specify at least one replicationSpec.<region> document. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections. Important MongoDB does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC. Provider Region Names AWS US_EAST_1 US_EAST_2 US_WEST_1 US_WEST_2 CA_CENTRAL_1 EU_WEST_1 EU_WEST_2 EU_WEST_3 EU_CENTRAL_1 AP_NORTHEAST_1 AP_NORTHEAST_2 AP_SOUTHEAST_1 AP_SOUTHEAST_2 AP_SOUTH_1 SA_EAST_1 GCP Note EASTERN_US corresponds to the GCP us_east_1 region. EASTERN_US US_EAST_4 CENTRAL_US WESTERN_US NORTH_AMERICA_NORTHEAST_1 SOUTH_AMERICA_EAST_1 WESTERN_EUROPE EUROPE_WEST_2 EUROPE_WEST_3 EUROPE_WEST_4 EASTERN_ASIA_PACIFIC NORTHEASTERN_ASIA_PACIFIC SOUTHEASTERN_ASIA_PACIFIC ASIA_SOUTH_1 AUSTRALIA_SOUTHEAST_1 AZURE US_CENTRAL US_EAST US_EAST_2 US_NORTH_CENTRAL US_WEST US_SOUTH_CENTRAL EUROPE_NORTH EUROPE_WEST FRANCE_CENTRAL US_WEST_2 CANADA_EAST CANADA_CENTRAL BRAZIL_SOUTH AUSTRALIA_EAST AUSTRALIA_SOUTH_EAST UK_SOUTH UK_WEST INDIA_CENTRAL INDIA_WEST INDIA_SOUTH ASIA_EAST JAPAN_EAST JAPAN_WEST ASIA_SOUTH_EAST KOREA_CENTRAL KOREA_SOUTH For each <region> document, you must specify the electableNodes, priority, and readOnlyNodes fields.
replicationSpec.<region>.electableNodes	integer	Required The number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads. The total number of electableNodes across all replicationSpec.<region> document must be 3, 5, or 7. Specify 0 if you do not want any electable nodes in the region. You cannot create electable nodes if the replicationSpec.<region>.priority is 0.
replicationSpec.<region>.priority	integer	Required The election priority of the region. For regions with only replicationSpec.<region>.readOnlyNodes, set this value to 0. For regions where replicationSpec.<region>.electableNodes is at least 1, each replicationSpec.<region> must have a priority of exactly one (1) less than the previous region. The first region must have a priority of 7. The lowest possible priority is 1. The priority 7 region identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority. For example, if you have three regions, their priorities would be 7, 6, and 5 respectively. If you added two more regions for supporting electable nodes, the priorities of those regions would be 4 and 3 respectively.
replicationSpec.<region>.readOnlyNodes	integer	Required The number of read-only nodes for Atlas to deploy to the region. Read-only nodes can never become the primary, but can facilitate local-reads. Specify 0 if you do not want any read-only nodes in the region.
replicationSpecs	array of documents	Optional The configuration for each zone in a Global Cluster. Each document in this array represents a zone where Atlas deploys nodes for your Global Cluster. Use the replicationSpec parameter to create a multi-region cluster. Note You cannot specify both the replicationSpec and replicationSpecs parameters in the same request body.
replicationSpecs[n].id	string	Optional Unique identifier of the replication document.
replicationSpecs[n].zoneName	string	Required The name for the zone.
replicationSpecs[n].numShards	int	Required The number of shards to deploy in the specified zone.
replicationSpecs[n].regionsConfig	document	Required The physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region. You must order each regionsConfigs document by regionsConfig.priority, descending. During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block. For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections. Important MongoDB does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC. Provider Region Names AWS US_EAST_1 US_EAST_2 US_WEST_1 US_WEST_2 CA_CENTRAL_1 EU_WEST_1 EU_WEST_2 EU_WEST_3 EU_CENTRAL_1 AP_NORTHEAST_1 AP_NORTHEAST_2 AP_SOUTHEAST_1 AP_SOUTHEAST_2 AP_SOUTH_1 SA_EAST_1 GCP Note EASTERN_US corresponds to the GCP us_east_1 region. EASTERN_US US_EAST_4 CENTRAL_US WESTERN_US NORTH_AMERICA_NORTHEAST_1 SOUTH_AMERICA_EAST_1 WESTERN_EUROPE EUROPE_WEST_2 EUROPE_WEST_3 EUROPE_WEST_4 EASTERN_ASIA_PACIFIC NORTHEASTERN_ASIA_PACIFIC SOUTHEASTERN_ASIA_PACIFIC ASIA_SOUTH_1 AUSTRALIA_SOUTHEAST_1 AZURE US_CENTRAL US_EAST US_EAST_2 US_NORTH_CENTRAL US_WEST US_SOUTH_CENTRAL EUROPE_NORTH EUROPE_WEST FRANCE_CENTRAL US_WEST_2 CANADA_EAST CANADA_CENTRAL BRAZIL_SOUTH AUSTRALIA_EAST AUSTRALIA_SOUTH_EAST UK_SOUTH UK_WEST INDIA_CENTRAL INDIA_WEST INDIA_SOUTH ASIA_EAST JAPAN_EAST JAPAN_WEST ASIA_SOUTH_EAST KOREA_CENTRAL KOREA_SOUTH
replicationSpecs[n] .regionsConfig.electableNodes	ingteger	Required The number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpecs[n] .regionsConfig.readOnlyNodes	integer	Required The number of read-only nodes for Atlas to deploy to the region. Read-only nodes can never become the primary, but can facilitate local-reads. Specify 0 if you do not want any read-only nodes in the region.
replicationSpecs[n] .regionsConfig.priority	integer	Required The election priority of the region. For regions with only read-only nodes, set this value to 0.
diskSizeGB	double	Optional AWS / GCP ONLY The size in gigabytes of the server’s root volume. You can add capacity by increasing this number, up to a maximum possible value of 4096 (i.e., 4 TB). This value must be a positive integer. The minimum disk size for dedicated clusters is 10GB for AWS and GCP, and 32GB for Azure. If you specify diskSizeGB with a lower disk size, Atlas defaults to the minimum disk size value. Important Atlas calculates storage charges differently depending on whether you choose the default value or a custom value. For details, see Storage Capacity. Note The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster tier. If you require additional storage space beyond this limitation, consider upgrading your cluster to a higher tier.

HTTP Response Elements

Name	Type	Description
autoScaling	document	Contains the diskGBEnabled field which specifies whether to enable or disable disk auto-scaling.
autoScaling.diskGBEnabled	boolean	Specifies whether disk auto-scaling is enabled. The default is true. Set to true to enable disk auto-scaling. Set to false to disable disk auto-scaling.
backupEnabled	Boolean	If true, the cluster uses Atlas Continuous Backups for backing up cluster data. If backupEnabled and providerBackupEnabled are false, the cluster does not use Atlas backups.
biConnector	document	Information on whether BI Connector for Atlas is enabled or disabled for the cluster. The BI Connector for Atlas is only available for M10+ clusters. The biConnector document includes the following fields: Field Description enabled true if BI Connector for Atlas is enabled. false if BI Connector for Atlas is disabled. readPreference "primary" if BI Connector for Atlas reads from the primary. "secondary" if BI Connector for Atlas reads from a secondary.
clusterType	string	Specifies the type of the cluster: REPLICASET - replica set SHARDED - sharded cluster GEOSHARDED - Global Cluster
diskSizeGB	double	** AWS / GCP Only ** The size in gigabytes of the server’s root volume. You can add capacity by increasing this number, up to a maximum possible value of 4096 (i.e., 4 TB). Each instance size has its own default value. To view default values: Open the Atlas web interface. Click the button to add a new cluster. View the available default sizes. Close the window without saving changes.
encryptionAtRestProvider	string	Specify AWS to enable Encryption at Rest using the Atlas project AWS Key Management System settings. The cluster must meet the following restrictions: providerSettings.providerName must be AWS or AZURE. providerSettings.instanceSizeName must be M10 or greater. clusterType must be REPLICASET. backupEnabled must be false or omitted. For complete documentation on Encryption at Rest restrictions, see Restrictions. You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest via AWS KMS.
groupId	string	ID of the project the cluster belongs to.
id	string	ID of the cluster.
mongoDBVersion	string	The version of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersion	string	The major version of MongoDB the cluster runs: 3.2 [1] 3.4 3.6
mongoURI	string	The base connection string for the cluster. Include the following query parameters to use the mongoURI for connecting to the Atlas cluster replicaSet=<replica set name> (replica set clusters only) ssl=true authSource=admin Include a username and password for a MongoDB user associated to the Atlas project directly after the mongodb:// protocol portion of the mongoURI. To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Add MongoDB Users. You cannot connect to a Atlas cluster using mongoURI without all the specified query parameters and the user authentication information. Atlas only displays this field after the cluster is operational, not while it builds the cluster.
mongoURIUpdated	string	Lists when the connection string was last updated. The connection string changes, for example, if you change a replica set to a sharded cluster. Atlas only displays this field after the cluster is operational, not while it builds the cluster.
mongoURIWithOptions	string	The connection string for connecting to the Atlas cluster. Includes the replicaSet, ssl, and authSource query parameters in the connection string with values appropriate for the cluster. Include a username and password for a MongoDB user associated to the Atlas project directly after the mongodb:// protocol portion of the mongoURI. To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Add MongoDB Users. You cannot connect to a Atlas cluster using mongoURIWithOptions without the user authentication information. Atlas only displays this field after the cluster is operational, not while it builds the cluster.
name	string	The name of the cluster as it appears in Atlas.
numShards	integer	Selects whether the cluster is a sharded cluster or a replica set and specifies the number of shards for a sharded cluster. If this is set to 1, the cluster is a replica set. For more information on MongoDB replica sets, see Replication in the MongoDB manual. If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified. For more information on sharded clusters, see Sharding in the MongoDB manual. For details on how this setting affects costs, see Number of Servers. The possible values are 1 through 12. Note Not present in the response body for Global Clusters.
paused	boolean	A flag that indicates whether the cluster is paused or not.
providerBackupEnabled	Boolean	If true, the cluster uses Cloud Provider Snapshots for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups. If numShards is greater than 1, you cannot enable this option.
providerSettings	document	The configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.providerName	string	The cloud service provider on which the servers are provisioned. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure TENANT - Indicates an M2 or M5 multi-tenant cluster. See providerSettings.backingProviderName for the cloud service provider on which the server hosting the cluster is provisioned.
providerSettings.backingProviderName	string	The cloud service provider on which the multi-tenant server is provisioned. Only visible if providerSettings.providerName is TENANT. The possible values are: AWS - Amazon AWS GCP - Google Cloud Platform AZURE - Microsoft Azure
providerSettings.regionName	string	The physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases. For multi-region clusters, see replicationSpec.<region>.
providerSettings.instanceSizeName	string	The name of the instance size used for the Atlas cluster. M0 M2 M5 M10 ( AWS and GCP only ) M20 M30 M40 R40 ( AWS only ) M50 R40 ( AWS only ) M60 R60 ( AWS only ) M80 ( GCP only ) R80 ( AWS only ) M90 ( Azure only ) M100 ( AWS only ) M140 ( AWS only ) M200 ( AWS and GCP only ) M300 ( AWS and GCP only ) R400 ( AWS only ) See Microsoft Azure, Google Cloud Platform, or Amazon Web Services for complete documentation of each instance size and its default resources for a given cloud service provider.
providerSettings.diskIOPS	integer	The maximum input/output operations per second (IOPS) the system can perform.
providerSettings.diskTypeName	string	Azure Only The disk type of the server’s root volume. The following table lists the possible values for this field, and their corresponding storage size. diskTypeName Storage Size P4 1 32GB P6 64GB P10 2 128GB P20 512GB P30 1024GB P40 2048GB P50 4095GB 1 Default for M20 and M30 Azure instances 2 Default for M40+ Azure instances
providerSettings.encryptEBSVolume	Boolean	AWS only. If enabled, the Amazon EBS encryption feature encrypts the server’s root volume for both data at rest within the volume and for data moving between the volume and the instance.
replicationFactor	number	The number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy. For multi-region clusters, add the total number of replicationSpec.<region>.electableNodes to calculate the replication factor of the cluster. If your cluster is a sharded cluster, each shard is a replica set with the specified replication factor. For information on how the replication factor affects costs, see Number of Servers. For more information on MongoDB replica sets, see Replication in the MongoDB manual. The possible values are 3, 5, or 7.
replicationSpec	document	The configuration of each region in the cluster. Each element in this document represents a region where Atlas deploys your cluster.
replicationSpec.<region>	document	The physical location of the region. The <region> string corresponds to a region where Atlas deploys your cluster. Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.
replicationSpec.<region>.electableNodes	integer	The number of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec.<region>.priority	integer	The election priority of the region. The highest possible priority is 7, which identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. The lowest possible priority is 0, which identifies a read only region. You can have any number of priority 0 read only regions. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority.
replicationSpec.<region>.readOnlyNodes	integer	The number of read-only nodes in the region. Read-only nodes can never become the primary, but can facilitate local-reads.
replicationSpecs	array of documents	The configuration for each zone in a Global Cluster. Each document in this array represents a zone where Atlas deploys nodes for your Global Cluster.
replicationSpecs[n].id	string	Unique identifier of the the replication document.
replicationSpecs[n].zoneName	string	The name for the zone.
replicationSpecs[n].numShards	int	The number of shards to deploy in the specified zone.
replicationSpecs[n].regionsConfig	document	The physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.
srvAddress	string	Connection string for connecting to the Atlas cluster. The +srv modifier forces the connection to use TLS/SSL. See the mongoURI for additional options.
stateName	string	The current state of the cluster. The possible states are: IDLE CREATING UPDATING DELETING DELETED REPAIRING

Example

Request

Single Region Cluster Creation

copy

curl -u "username:apiKey" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters" --data '
{
  "name" : "DataStore2",
  "diskSizeGB" : 160,
  "numShards" : 1,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 480,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "US_EAST_1"
  },
  "replicationFactor" : 3,
  "backupEnabled" : true,
  "encryptionAtRestProvider" : "AWS",
  "autoScaling":{"diskGBEnabled":true}
}'

Multi Region Cluster Creation

copy

curl -u "username:apiKey" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters" --data '
{
  "name" : "DataStore2",
  "diskSizeGB" : 160,
  "numShards" : 1,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 480,
    "instanceSizeName" : "M10"
  },
  "replicationSpec": {
      "US_EAST_1": {
        "electableNodes": 3,
        "priority": 7,
        "readOnlyNodes" : 0
      },
      "US_EAST_2": {
        "electableNodes": 2,
        "priority" : 6,
        "readOnlyNodes" : 0
      },
      "US_WEST_1": {
        "electableNodes" : 2,
        "priority" : 5,
        "readOnlyNodes": 2
      }
  },
  "backupEnabled" : false,
  "encryptionAtRestProvider" : "AWS",
}'

Global Cluster Creation

copy

curl -X POST -i --digest --user "{username}:{apiKey}" --header "Content-Type: application/json" \
  "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters?pretty=true" \
  --data '
  {
    "name": "DataStore2",
    "diskSizeGB": 160,
     "providerSettings": {
       "providerName": "AWS",
       "diskIOPS": 480,
       "instanceSizeName": "M10"
     },
     "replicationSpecs": [{
       "zoneName": "Zone 1",
       "numShards": 2,
       "regionsConfig": {
         "US_EAST_1": {
           "electableNodes": 3,
           "readOnlyNodes": 0,
           "priority": 7
         }
       }
     },
     {
       "zoneName": "Zone 2",
       "numShards": 2,
       "regionsConfig": {
         "EU_CENTRAL_1": {
           "electableNodes": 3,
           "readOnlyNodes": 0,
           "priority": 7
         }
       }
     }],
     "backupEnabled": false,
     "providerBackupEnabled" : true,
     "clusterType": "GEOSHARDED"
  }'

Response

Single Region Cluster Response

copy

{
   "autoScaling":{"diskGBEnabled":true},
   "backupEnabled" : false,
   "biConnector": {
     "enabled": false,
     "readPreference": "secondary"
   },
   "clusterType": "REPLICASET",
   "diskSizeGB" : 160,
   "encryptionAtRestProvider" : "AWS",
   "groupId" : "5356823b3794de37132bb7b",
   "id": "59ef6621c0c6e378559875ed",
   "links" : [
      {
         "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/DataStore2",
         "rel" : "self"
      }
   ],
   "mongoDBMajorVersion" : "3.4",
   "mongoDBVersion" : "3.4.9",
   "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "mongoURIUpdated" : "2017-10-23T21:26:17Z",
   "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongoe-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
   "name" : "DataStore2",
   "numShards" : 1,
   "paused" : false,
   "providerBackupEnabled" : true,
   "providerSettings" : {
      "providerName" : "AWS",
      "diskIOPS" : 480,
      "encryptEBSVolume" : false,
      "instanceSizeName" : "M40",
      "regionName" : "US_EAST_1"
   },
   "providerBackupEnabled" : "false",
   "replicationFactor" : 3,
   "replicationSpec": {
       "US_EAST_1": {
           "electableNodes": 3,
           "priority": 7,
           "readOnlyNodes": 0
       }
   },
   "srvAddress" : "mongodb+srv://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "stateName" : "CREATING"
}

Multi Region Cluster Response

copy

{
   "backupEnabled": false,
   "biConnector": {
     "enabled": false,
     "readPreference": "secondary"
   },
   "clusterType": "REPLICASET",
   "diskSizeGB": 160.0,
   "encryptionAtRestProvider" : "AWS",
   "groupId": "5356823b3794de37132bb7b",
   "id": "59ef6621c0c6e378559875ed",
   "links": [{
      "href": "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/DataStore2",
      "rel": "self"
   }],
   "mongoDBMajorVersion": "3.4",
   "mongoDBVersion": "3.4.9",
   "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "mongoURIUpdated" : "2017-10-23T21:26:17Z",
   "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
   "name": "DataStore2",
   "numShards": 1,
   "paused" : false,
   "providerBackupEnabled" : false,
   "providerSettings": {
      "providerName": "AWS",
      "diskIOPS": 480,
      "encryptEBSVolume": true,
      "instanceSizeName": "M10"
   },
   "replicationSpec": {
      "US_EAST_1": {
         "electableNodes": 3,
         "priority": 7,
         "readOnlyNodes": 0
      },
      "US_EAST_2": {
         "electableNodes": 2,
         "priority": 6,
         "readOnlyNodes": 0
      },
      "US_WEST_1": {
         "electableNodes": 2,
         "priority": 5,
         "readOnlyNodes": 2
      }
   },
   "srvAddress" : "mongodb+srv://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "stateName": "CREATING"
}

Global Cluster Response

copy

{
  "autoScaling" : {
    "diskGBEnabled" : true
  },
  "backupEnabled" : false,
  "biConnector" : {
    "enabled" : false,
    "readPreference" : "secondary"
  },
  "clusterType" : "GEOSHARDED",
  "diskSizeGB" : 160.0,
  "encryptionAtRestProvider" : "NONE",
  "groupId" : "6c392af480eef519ea5deeb1",
  "id" : "5b3fb5ab80eef5429067ebd9",
  "links" : [ {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/DataStore2",
    "rel" : "self"
    }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/DataStore2/restoreJobs",
    "rel" : "http://mms.mongodb.com/restoreJobs"
  }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/DataStore2/snapshots",
    "rel" : "http://mms.mongodb.com/snapshots"
  } ],
  "mongoDBMajorVersion" : "3.6",
  "mongoDBVersion" : "3.6.5",
  "mongoURIUpdated" : "2018-07-06T18:32:11Z",
  "name" : "DataStore2",
  "paused" : false,
  "providerBackupEnabled" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 480,
    "encryptEBSVolume" : true,
    "instanceSizeName" : "M10"
  },
  "replicationSpecs" : [ {
    "id" : "5b48f5a780eef5236f689f94",
    "numShards" : 2,
    "regionsConfig" : {
      "US_EAST_1" : {
        "electableNodes" : 3,
        "priority" : 7,
        "readOnlyNodes" : 0
      }
    },
    "zoneName" : "Zone 1"
    }, {
    "numShards" : 2,
    "regionsConfig" : {
      "EU_CENTRAL_1" : {
        "electableNodes" : 3,
        "priority" : 7,
        "readOnlyNodes" : 0
      }
    },
    "zoneName" : "Zone 2"
  } ],
  "stateName" : "CREATING"
}

[1]	(1, 2) MongoDB Server 3.2 is planned for End of Life on September 2018. Atlas deprecated support for deploying clusters with MongoDB 3.2 in March, 2018.

←   Get Advanced Configuration Options for One Cluster Modify a Cluster  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.