> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/api-reference/databases/mongodb/clusters-1/create-a-cluster.md).

# Create a Cluster

Creates a new MongoDB cluster.

```json
{"openapi":"3.0.3","info":{"title":"IONOS DBaaS MongoDB REST API","version":"1.0.0"},"tags":[{"name":"Clusters","description":"A cluster, in this context, describes a grouping of multiple MongoDB instances into a *replica set* or a *sharded cluster*."}],"servers":[{"url":"https://api.ionos.com/databases/mongodb","description":"Production"}],"security":[{"basicAuth":[]},{"tokenAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"For 'Basic' authentication, take your credentials by first combining the username and password with a colon (``username:password``) and then encoding the resulting string in base64 (``YWxhZGRpbjpvcGVuc2VzYW1l``).\n\n**Example Request Header**\n\n``Authorization: Basic YWxhZGRpbjpvcGVuc2Vzl``\n\nMore details: https://en.wikipedia.org/wiki/Basic_access_authentication\n"},"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization is granted when a valid proof of identity is provided along with an API request for data. This proof of identity is in the form of a JSON web access token, a unique string that identifies a user.\n\n**Example Request Header**\n\n``Authorization: Bearer ACCESS_TOKEN``\n"}},"schemas":{"CreateClusterRequest":{"description":"The request payload with all data needed to create a new MongoDB cluster.\n","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"},"properties":{"$ref":"#/components/schemas/CreateClusterProperties"}},"type":"object"},"Metadata":{"description":"The metadata of the resource.","properties":{"createdDate":{"type":"string","format":"date-time","description":"The date the resource was created."},"createdBy":{"type":"string","description":"The user who created the resource."},"createdByUserId":{"type":"string","description":"The ID of the user who created the resource."},"lastModifiedDate":{"type":"string","format":"date-time","description":"The date the resource was last modified."},"lastModifiedBy":{"type":"string","description":"The last user who modified the resource."},"lastModifiedByUserId":{"type":"string","description":"The ID of the user who last modified the resource."},"state":{"$ref":"#/components/schemas/State"},"health":{"$ref":"#/components/schemas/Health"}}},"State":{"description":"The current status reported by the cluster.\n* **AVAILABLE** Resources for this cluster exist and are healthy.\n* **BUSY** Resources for this cluster are being created or updated.\n* **DESTROYING** Delete cluster command was issued, the cluster is being deleted.\n* **FAILED** Failed to get the cluster status.\n* **UNKNOWN** The state is unknown.\n* **UPGRADING** The cluster is upgrading to a different edition.\n","type":"string","enum":["AVAILABLE","BUSY","DESTROYING","FAILED","UNKNOWN","UPGRADING"]},"Health":{"description":"The current health status reported by the cluster.\n* **HEALTHY** Primary exists and number of replicas is equal to specified.\n* **UNHEALTHY** Primary does not exist or cluster doesn't have majority.\n* **DEGRADED** Primary exists and number of replicas is less than specified.\n* **UNKNOWN** The health status is unknown.\n","type":"string","enum":["HEALTHY","UNHEALTHY","DEGRADED","UNKNOWN"]},"CreateClusterProperties":{"description":"The properties with all the data needed to create a new MongoDB cluster.\n","required":["mongoDBVersion","instances","connections","location","displayName"],"properties":{"type":{"$ref":"#/components/schemas/Type"},"templateID":{"$ref":"#/components/schemas/TemplateID"},"mongoDBVersion":{"$ref":"#/components/schemas/MongoDBVersion"},"instances":{"$ref":"#/components/schemas/Instances"},"shards":{"$ref":"#/components/schemas/Shards"},"connections":{"type":"array","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/Connection"}},"location":{"$ref":"#/components/schemas/Location"},"backup":{"$ref":"#/components/schemas/BackupProperties"},"displayName":{"$ref":"#/components/schemas/DisplayName"},"maintenanceWindow":{"$ref":"#/components/schemas/MaintenanceWindow"},"biConnector":{"$ref":"#/components/schemas/BiConnectorProperties"},"fromBackup":{"$ref":"#/components/schemas/CreateRestoreRequest"},"edition":{"$ref":"#/components/schemas/Edition"},"cores":{"$ref":"#/components/schemas/Cores"},"ram":{"$ref":"#/components/schemas/Ram"},"storageSize":{"$ref":"#/components/schemas/StorageSize"},"storageType":{"$ref":"#/components/schemas/StorageType"}},"type":"object"},"Type":{"type":"string","description":"The cluster type, either `replicaset` or `sharded-cluster`.\n"},"TemplateID":{"type":"string","description":"The unique ID of the template, which specifies the number of cores, storage size, and memory.\nYou cannot downgrade to a smaller template or minor edition; for example, downgrading from *Business* to *Playground* is not possible.\nTo get a list of all templates to confirm the changes, use the '/templates' endpoint.\n"},"MongoDBVersion":{"type":"string","description":"The MongoDB version of your cluster."},"Instances":{"type":"integer","description":"The total number of instances in the cluster (one primary and n-1 secondaries).\n"},"Shards":{"type":"integer","description":"The total number of shards in the cluster.\n"},"Connection":{"description":"The network connection  details for your cluster.","properties":{"datacenterId":{"description":"The datacenter to which your cluster will be connected.","type":"string"},"lanId":{"description":"The numeric LAN ID with which you connect your cluster.","type":"string"},"cidrList":{"type":"array","items":{"type":"string"},"description":"The list of IPs for your cluster.\nAll IPs must be in a /24 network.\nNote the following unavailable IP ranges:\n10.233.114.0/24\n"}},"required":["datacenterId","lanId","cidrList"],"type":"object"},"Location":{"type":"string","description":"The physical location where the cluster will be created. This is the location where all your instances will be located. This property is immutable.\n"},"BackupProperties":{"type":"object","description":"Backup related properties.\n","properties":{"location":{"type":"string","description":"The location where the cluster backups will be stored. If not set, the backup is stored in the nearest location of the cluster.\n"}}},"DisplayName":{"type":"string","description":"The name of your cluster."},"MaintenanceWindow":{"description":"A weekly window of 4 hours during which maintenance work can be performed.\n","properties":{"time":{"type":"string"},"dayOfTheWeek":{"$ref":"#/components/schemas/DayOfTheWeek"}},"required":["time","dayOfTheWeek"],"type":"object"},"DayOfTheWeek":{"description":"The week day.","type":"string","enum":["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"]},"BiConnectorProperties":{"properties":{"enabled":{"type":"boolean","description":"The MongoDB Connector for Business Intelligence allows you to query a MongoDB database\nusing SQL commands to aid in data analysis.\n","default":false},"host":{"type":"string","description":"The host where this new BI Connector is installed.\n","readOnly":true},"port":{"type":"string","description":"Port number used when connecting to this new BI Connector.\n","readOnly":true}}},"CreateRestoreRequest":{"description":"The restore request.","properties":{"snapshotId":{"type":"string","description":"The unique ID of the snapshot you want to restore."},"recoveryTargetTime":{"type":"string","format":"date-time","description":"If this value is supplied as ISO 8601 timestamp, the backup will be\nreplayed up until the given timestamp.\n"}},"type":"object"},"Edition":{"type":"string","description":"The cluster edition."},"Cores":{"type":"integer","description":"The number of CPU cores per instance.","minimum":1},"Ram":{"type":"integer","description":"The amount of memory per instance in megabytes. Has to be a multiple of 1024.","multipleOf":1024,"minimum":2048},"StorageSize":{"type":"integer","description":"The amount of storage per instance in megabytes.","minimum":2048,"maximum":2097152},"StorageType":{"description":"The storage type used in your cluster.","type":"string","enum":["HDD","SSD Standard","SSD Premium"]},"ClusterResponse":{"description":"A database cluster.","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/ResourceType"}]},"id":{"$ref":"#/components/schemas/ResourceId"},"metadata":{"$ref":"#/components/schemas/Metadata"},"properties":{"$ref":"#/components/schemas/ClusterProperties"}},"type":"object"},"ResourceType":{"description":"The resource type.","type":"string","enum":["collection","cluster","user","snapshot","template"]},"ResourceId":{"type":"string","description":"The unique ID of the resource."},"ClusterProperties":{"description":"Properties of a database cluster.","properties":{"type":{"$ref":"#/components/schemas/Type"},"displayName":{"$ref":"#/components/schemas/DisplayName"},"mongoDBVersion":{"$ref":"#/components/schemas/MongoDBVersion"},"location":{"$ref":"#/components/schemas/Location"},"backup":{"$ref":"#/components/schemas/BackupProperties"},"instances":{"$ref":"#/components/schemas/Instances"},"shards":{"$ref":"#/components/schemas/Shards"},"connections":{"type":"array","minItems":1,"maxItems":1,"items":{"$ref":"#/components/schemas/Connection"}},"maintenanceWindow":{"$ref":"#/components/schemas/MaintenanceWindow"},"templateID":{"$ref":"#/components/schemas/TemplateID"},"connectionString":{"$ref":"#/components/schemas/ConnectionString"},"biConnector":{"$ref":"#/components/schemas/BiConnectorProperties"},"edition":{"$ref":"#/components/schemas/Edition"},"cores":{"$ref":"#/components/schemas/Cores"},"ram":{"$ref":"#/components/schemas/Ram"},"storageSize":{"$ref":"#/components/schemas/StorageSize"},"storageType":{"$ref":"#/components/schemas/StorageType"}},"type":"object"},"ConnectionString":{"type":"string","description":"The connection string for your cluster."},"ErrorResponse":{"properties":{"httpStatus":{"type":"integer","description":"The HTTP status code of the operation."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ErrorMessage"}}},"type":"object"},"ErrorMessage":{"properties":{"errorCode":{"type":"string","description":"Application internal error code.\n"},"message":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n"}},"type":"object"}},"responses":{"ApiError":{"description":"Any erroneous status code: 400 (parse error), 401 (authorization error),\n402 (trial access), 403 (insufficient permissions), 404 (not found),\n405 (unsupported HTTP method), 415 (unsupported content type),\n422 (validation error), 429 (request rate limit exceeded),\n500 (server error), 503 (maintenance)\n","headers":{"Content-Type":{"description":"The content type of the response.","schema":{"type":"string","default":"application/problem+json"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/clusters":{"post":{"operationId":"clustersPost","summary":"Create a Cluster","description":"Creates a new MongoDB cluster.\n","tags":["Clusters"],"requestBody":{"description":"The cluster to be created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClusterRequest"}}},"required":true},"responses":{"200":{"description":"The created cluster is returned and is automatically set to `state = BUSY`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterResponse"}}}},"default":{"$ref":"#/components/responses/ApiError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/api-reference/databases/mongodb/clusters-1/create-a-cluster.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.