> 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/v2-2/mongodb-v2-api-workflows.md).

# MongoDB v2 API Workflows

Use these end-to-end workflows to deploy, connect, operate, and restore resources using the IONOS CLOUD DBaaS MongoDB v2 API.

* **Deploy a MongoDB cluster:** Plan your cluster configuration and provision it through to the `AVAILABLE` state.
* **Connect to your MongoDB cluster:** Connect to a provisioned cluster using its connection URI and credentials.
* **Operate a MongoDB cluster:** Manage a running cluster with day-to-day operations and deprovision it when no longer needed.
* **Restore from a snapshot:** Recover cluster data to a specific point in time using Point-in-Time Recovery (PITR).
* **Verify snapshot data residency:** Confirm that cluster snapshots are stored in the expected Object Storage region.

{% hint style="info" %}
**Note:** If an operation returns an error, see the response details of each operation for API-specific error codes. For generic HTTP status codes used across IONOS CLOUD APIs, see [<mark style="color:blue;">HTTP Status Codes</mark>](https://docs.ionos.com/cloud/api-reference/readme/getting-started#http-status-codes).
{% endhint %}

### Deploy a MongoDB Cluster

Use this workflow to plan and provision a new MongoDB cluster.

#### Prerequisites

* An access token that authenticates your API requests. For more information, see [<mark style="color:blue;">Authentication</mark>](#tag/Authentication).
* The Universally Unique Identifier (UUID) of an existing Virtual Data Center (VDC) (`datacenterId`) that resides in the same region as your target MongoDB endpoint. To create a VDC, use [<mark style="color:blue;">IONOS CLOUD API</mark>](https://docs.ionos.com/cloud/api-reference/cloud-api-v6/data-centers).
* The identifier of a private Local Area Network (LAN) (`lanId`) within that VDC. The cluster connects to this LAN during provisioning. To create a LAN, use [<mark style="color:blue;">IONOS CLOUD API</mark>](https://docs.ionos.com/cloud/api-reference/cloud-api-v6/lans).
* Static IP addresses in Classless Inter-Domain Routing (CIDR) notation (`instanceAddresses`): one for each instance of the cluster, or exactly three for an `ENTERPRISE` cluster with sharding enabled. Example: `192.168.2.101/24`. The range `10.208.0.0/12` is unavailable.

{% stepper %}
{% step %}

#### Plan Configuration

1. **Find the snapshot location:** Specify the region where your cluster's snapshots are stored.

   * **API:** [<mark style="color:blue;">Retrieve all SnapshotLocations</mark>](#tag/SnapshotLocations/operation/snapshotlocationsGet)
   * **Action:** Browse the list to identify an available snapshot region.
   * **Result:** The API returns HTTP `200` with a list of snapshot locations. Note the `location` value to use in `properties.snapshot.location` when provisioning the cluster.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> For geographic data safety, choose a snapshot location in a different region from your cluster endpoint.</p></div>
2. **Select a MongoDB version:** Retrieve the list of supported MongoDB versions.
   * **API:** [<mark style="color:blue;">Retrieve all Versions</mark>](#tag/Versions/operation/versionsGet)
   * **Action:** Identify the version that matches your requirements.
   * **Result:** The API returns HTTP `200` with a list of supported MongoDB versions. Each entry includes the version identifier, its lifecycle `status` (`BETA`, `SUPPORTED`, `RECOMMENDED`, or `DEPRECATED`), a `canUpgradeTo` array listing available upgrade paths, and the lifecycle dates `creationFreezeDate` and `deprecationDate`. Note the version identifier to use for `properties.version` when provisioning the cluster.
3. **Choose an edition:** Select the edition that matches your requirements.

   * `BUSINESS`: Retrieve the available instance templates with [<mark style="color:blue;">Retrieve all InstanceTemplates</mark>](#tag/InstanceTemplates/operation/instancetemplatesGet). Each template defines `cores`, `ram`, and `storageSize`. Note the `id` of the template to use as `instanceTemplateId`.
   * `ENTERPRISE`: Define the resources yourself in the `instances` object (`count`, `ram`, `cores`, and `storageSize`). Optionally activate sharding (`sharding.enabled` and `sharding.shards`, from 2 to 5) and the BI Connector (`biConnectorEnabled`).

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> When sharding is enabled, <code>instances.count</code> is the number of replicas per shard.</p></div>

{% endstep %}

{% step %}

#### Provision a Cluster

1. **Create the cluster:**

   * **API:** [<mark style="color:blue;">Create Cluster</mark>](#tag/Clusters/operation/clustersPost)
   * **Action:** Provide the required fields: `edition`, `name`, `version`, `connection` (containing `datacenterId`, `lanId`, and `instanceAddresses`), `snapshot` (containing `location` and `retentionDays`), `maintenanceWindow`, and `credentials` (containing `username`, `password`, and `database`). For `BUSINESS`, also provide `instanceTemplateId` and `instanceCount`. For `ENTERPRISE`, also provide `instances`.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong></p><ul><li><code>connection.datacenterId</code> and <code>connection.lanId</code> cannot be changed after the cluster is created. Confirm they are correct before submitting this request.</li><li>The number of <code>instanceAddresses</code> must match the number of instances in the cluster. For an <code>ENTERPRISE</code> cluster with sharding enabled, provide exactly three addresses. This applies regardless of the instance count and the number of shards. They are used by the three config servers that store the cluster metadata, which are separate from the shard instances.</li><li><p><code>logsEnabled</code> and <code>metricsEnabled</code> are optional. Set either to <code>true</code> to activate log or metrics forwarding.</p><ul><li><code>logsEnabled</code> requires the IONOS CLOUD <a href="https://docs.ionos.com/cloud/api-reference/observability/logging-service/central"><mark style="color:blue;">Logging Service</mark></a> to be activated on your contract.</li><li><code>metricsEnabled</code> requires the IONOS CLOUD <a href="https://docs.ionos.com/cloud/api-reference/observability/monitoring-service/central"><mark style="color:blue;">Monitoring Service</mark></a> to be activated on your contract. Activating either service incurs extra costs.</li></ul></li></ul></div>

Example request bodies for each edition:

{% tabs %}
{% tab title="Enterprise" %}

```json
{
  "properties": {
    "edition": "ENTERPRISE",
    "name": "cms-prod",
    "version": "7",
    "instances": {
      "count": 3,
      "ram": 8,
      "cores": 4,
      "storageSize": 100
    },
    "connection": {
      "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
      "lanId": "2",
      "instanceAddresses": [
        "192.168.2.101/24",
        "192.168.2.102/24",
        "192.168.2.103/24"
      ]
    },
    "snapshot": {
      "location": "eu-south-2",
      "retentionDays": 7
    },
    "maintenanceWindow": {
      "dayOfTheWeek": "Sunday",
      "time": "02:00:00"
    },
    "credentials": {
      "username": "my_db_user",
      "password": "S3cure!Pass",
      "database": "mydb"
    }
  }
}
```

{% endtab %}

{% tab title="Business" %}

```json
{
  "properties": {
    "edition": "BUSINESS",
    "name": "cms-prod",
    "version": "7",
    "instanceTemplateId": "dcd31531-3ac8-11eb-9feb-046c59cc737e",
    "instanceCount": 3,
    "connection": {
      "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
      "lanId": "2",
      "instanceAddresses": [
        "192.168.2.101/24",
        "192.168.2.102/24",
        "192.168.2.103/24"
      ]
    },
    "snapshot": {
      "location": "eu-south-2",
      "retentionDays": 7
    },
    "maintenanceWindow": {
      "dayOfTheWeek": "Sunday",
      "time": "02:00:00"
    },
    "credentials": {
      "username": "my_db_user",
      "password": "S3cure!Pass",
      "database": "mydb"
    }
  }
}
```

{% endtab %}
{% endtabs %}

**Result:** The API returns HTTP `201`. Note the `id`: you need it in every subsequent cluster operation. `metadata.state` starts as `PROVISIONING`.

{% hint style="info" %}
**Note:**

* Cluster provisioning is asynchronous. Poll [<mark style="color:blue;">Retrieve Cluster</mark>](#tag/Clusters/operation/clustersFindById) until `metadata.state` is `AVAILABLE`. Once available, `metadata.connectionUri` contains the connection string.
* If `metadata.state` returns `FAILED`, the cluster failed to provision. Retrieve the cluster details using [<mark style="color:blue;">Retrieve Cluster</mark>](#tag/Clusters/operation/clustersFindById) and check `metadata.statusMessage` for the failure reason.
  {% endhint %}
  {% endstep %}
  {% endstepper %}

**Next steps:** To connect to your cluster, see [<mark style="color:blue;">Connect to Your MongoDB Cluster</mark>](#tag/MongoDB-API-Workflows).

### Connect to Your MongoDB Cluster

Use this workflow to retrieve the MongoDB cluster connection URI and connect using your credentials.

#### Prerequisites

* Ensure the cluster is in the `AVAILABLE` state.
* You must have the `id` (UUID) of the cluster. You receive this when you complete the [<mark style="color:blue;">Deploy a MongoDB Cluster</mark>](#tag/MongoDB-API-Workflows) workflow.
* You must have the `credentials.username`, `credentials.password`, and `credentials.database` set during provisioning.
* Your client must have network access to the LAN that the cluster is connected to.

{% stepper %}
{% step %}

#### Retrieve the Connection Details

1. **Retrieve the cluster:**
   * **API:** [<mark style="color:blue;">Retrieve Cluster</mark>](#tag/Clusters/operation/clustersFindById)
   * **Result:** The API returns HTTP `200`. Note `metadata.connectionUri`. Example: `mongodb+srv://m-12abd343.mongodb.gb-bhx.ionoscloud.com`.
     {% endstep %}

{% step %}

#### Connect with the Connection URI

Use the following details with `mongosh` or any MongoDB driver:

| **Property**                | **Value**                                          |
| --------------------------- | -------------------------------------------------- |
| **Connection URI**          | `metadata.connectionUri` value from the first step |
| **User**                    | The username from `credentials.username`           |
| **Authentication database** | `admin`                                            |

Example:

```bash
mongosh "mongodb+srv://m-12abd343.mongodb.gb-bhx.ionoscloud.com" \
  --username my_db_user \
  --authenticationDatabase admin
```

{% hint style="info" %}
**Note:** The user owns the database from `credentials.database`, but you authenticate against the `admin` database. The `mongodb+srv` connection URI sets this automatically.
{% endhint %}
{% endstep %}

{% step %}

#### Connect through the BI Connector (Optional)

On `ENTERPRISE` clusters with `biConnectorEnabled` set to `true`, the BI Connector is reachable over the MySQL wire protocol at `bi-connect.<mongo-host>` on the fixed port `27015`. Example: `bi-connect.m-12abd343.mongodb.gb-bhx.ionoscloud.com:27015`.
{% endstep %}
{% endstepper %}

### Operate a MongoDB Cluster

Use this workflow to manage a running cluster and deprovision it when it is no longer needed.

#### Prerequisites

* Ensure the cluster is in the `AVAILABLE` state.
* You must have the `id` (UUID) of the cluster.

{% hint style="info" %}
**Note:** Cluster updates use the Ensure pattern. Retrieve the cluster, change the fields you need, and submit the full object with [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut). Fields not included in the request reset to their defaults. Omit `credentials` to leave the existing user unchanged.
{% endhint %}

#### Review Snapshots

* **API:** [<mark style="color:blue;">Retrieve all Snapshots</mark>](#tag/Snapshots/operation/snapshotsGet)
* **Action:** Filter by `filter.clusterId` to list the snapshots of one cluster.
* **Result:** Each snapshot shows `earliestRecoveryTargetTime` and `latestRecoveryTargetTime`. If `latestRecoveryTargetTime` is `null`, the cluster can be restored up to the current time.

#### Scale Cluster Resources

* **API:** [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut)
* **Action:** For `BUSINESS`, change `instanceTemplateId` or `instanceCount`. For `ENTERPRISE`, change the values in `instances`. Submit the full cluster object. If the number of instances changes, update `connection.instanceAddresses` in the same request so that it contains exactly one address per instance. For example, increasing a three-instance cluster to four instances requires a fourth address in the list. For an `ENTERPRISE` cluster with sharding enabled, the list always contains exactly three addresses.
* **Result:** The API accepts the change and `metadata.state` moves to `UPDATING`. Poll until it returns to `AVAILABLE`.

#### Add Shards

* **API:** [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut)
* **Action:** On an `ENTERPRISE` cluster with sharding enabled, increase `sharding.shards` and submit the full cluster object.
* **Result:** The cluster moves to `UPDATING` and returns to `AVAILABLE` when the change completes.

{% hint style="info" %}
**Note:** You can increase the number of shards but not reduce it. Once sharding is enabled, you cannot disable it.
{% endhint %}

#### Monitor Version Lifecycle

* **API:** [<mark style="color:blue;">Retrieve all Versions</mark>](#tag/Versions/operation/versionsGet)
* **Action:** Check the `status`, `creationFreezeDate`, and `deprecationDate` of your cluster's version. A `DEPRECATED` status or an approaching `deprecationDate` indicates that you should plan an upgrade.

#### Upgrade the MongoDB Version

* **API:** [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut)
* **Action:** Set `properties.version` to a version listed in the `canUpgradeTo` array of your current version. Downgrades are not supported.

#### Update the Maintenance Window

* **API:** [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut)
* **Action:** Change `maintenanceWindow.dayOfTheWeek` and `maintenanceWindow.time` (UTC). The window is four hours long and starts at `time`.

#### Deprovision the Cluster

{% hint style="warning" %}
**Warning:** Deleting a cluster is irreversible. The cluster is permanently removed and cannot be recovered. Snapshots of the deleted cluster are kept until the end of the cluster's retention period (`snapshot.retentionDays`).
{% endhint %}

Deprovision the cluster when it is no longer needed to release resources.

* **API:** [<mark style="color:blue;">Delete Cluster</mark>](#tag/Clusters/operation/clustersDelete)
* **Action:** Submit the delete request to permanently remove the cluster.
* **Result:** The API returns HTTP `202`, confirming the delete request is accepted. Deletion is asynchronous: `metadata.state` moves to `DESTROYING` and the cluster is removed once deletion completes.

### Restore from a Snapshot

Use this workflow to recover cluster data to a specific point in time. MongoDB supports Point-in-Time Recovery (PITR): the restore starts from the base snapshot and replays the oplog up to `recoveryTargetDatetime`.

#### Prerequisites

* An access token that authenticates your API requests. For more information, see [<mark style="color:blue;">Authentication</mark>](#tag/Authentication).
* The `id` of the source cluster.

#### Step 1: Find the Snapshot

1. **List the snapshots:**
   * **API:** [<mark style="color:blue;">Retrieve all Snapshots</mark>](#tag/Snapshots/operation/snapshotsGet)
   * **Action:** Filter by `filter.clusterId`.
   * **Result:** Note the snapshot `id` and its recovery window (`earliestRecoveryTargetTime` to `latestRecoveryTargetTime`). Also note `requiredStorageSize`, the minimum storage needed to restore this snapshot, in MiB.

#### Path 1: Create a New Cluster from a Snapshot

* **API:** [<mark style="color:blue;">Create Cluster</mark>](#tag/Clusters/operation/clustersPost)
* **Action:** Provide the full cluster configuration and add `restoreFromSnapshot` with `sourceSnapshotId`. Optionally add `recoveryTargetDatetime`. If omitted, the snapshot is applied in full.
* **Result:** A new cluster is provisioned with the restored data.

{% hint style="info" %}
**Note:** Only snapshots from clusters in the same region are eligible. The snapshot's `requiredStorageSize` is in mebibytes (MiB), while `instances.storageSize` (Enterprise) and the instance template's `storageSize` (Business) are in gigabytes (GB). Convert the value before you choose the storage (1 GiB = 1,024 MiB) and round up. The new cluster's storage per instance must be at least that amount.
{% endhint %}

```json
{
  "properties": {
    "restoreFromSnapshot": {
      "sourceSnapshotId": "a8784665-3d99-5464-af32-30a2967f58e7",
      "recoveryTargetDatetime": "2026-10-10T13:37:50+01:00"
    }
  }
}
```

#### Path 2: Restore the Existing Cluster in Place

Use this path when you must recover the current cluster to an earlier state. This path is destructive and cannot be undone.

* **API:** [<mark style="color:blue;">Update Cluster</mark>](#tag/Clusters/operation/clustersPut)
* **Action:** Submit the full cluster object and add `restoreFromSnapshot` with `recoveryTargetDatetime` only. Do not set `sourceSnapshotId`: the source is inferred from the cluster's own snapshots.
* **Result:** The cluster is restored to the target time.

{% hint style="warning" %}
**Warning:** An in-place restore overwrites all current cluster data with the restored data. This action cannot be undone. The cluster may experience a brief period of downtime.
{% endhint %}

### Verify Snapshot Data Residency

Use this workflow to confirm that cluster snapshots are stored in the expected Object Storage region.

{% stepper %}
{% step %}

#### Find the Cluster's Snapshot Location

* **API:** [<mark style="color:blue;">Retrieve Cluster</mark>](#tag/Clusters/operation/clustersFindById)
* **Result:** Note `properties.snapshot.location`.
  {% endstep %}

{% step %}

#### Verify the Snapshot Location

* **API:** [<mark style="color:blue;">Retrieve all Snapshots</mark>](#tag/Snapshots/operation/snapshotsGet)
* **Action:** Filter by `filter.clusterId`.
* **Result:** Each snapshot's `location` should match the value from the first step.
  {% endstep %}
  {% endstepper %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/api-reference/databases/v2-2/mongodb-v2-api-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
