> 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/overview.md).

# Overview

The IONOS CLOUD DBaaS MongoDB v2 API provides managed MongoDB clusters on region-specific endpoints. It offers two editions (Business and Enterprise), an idempotent Ensure pattern for cluster updates, Point-in-Time Recovery (PITR) from snapshots, dedicated snapshot location management, token-only authentication, granular cluster lifecycle states, a declarative restore model, and direct integration with IONOS CLOUD Logging and Monitoring Services.

If you are new to the MongoDB v2 API, see [<mark style="color:blue;">What Can You Do With the MongoDB v2 API?</mark>](#section/Overview/What-Can-You-Do-With-the-MongoDB-v2-API). If you are migrating from v1, see [<mark style="color:blue;">MongoDB API Versions</mark>](#tag/MongoDB-API-Versions).

### What Can You Do With the MongoDB v2 API?

The IONOS CLOUD DBaaS [<mark style="color:blue;">MongoDB v2 API</mark>](#tag/Overview) provides a consistent way to manage the complete lifecycle of your highly available MongoDB clusters. Using the v2 API, you can:

* **Provision and modify clusters:** Create or update Business and Enterprise edition clusters on region-specific endpoints.
* **Scale with sharding:** On the Enterprise edition, activate sharding and the MongoDB BI Connector.
* **Recover to a point in time:** Restore a cluster from a snapshot to any moment within the snapshot's recovery window.
* **Control geographic data safety:** Query explicit Snapshot Locations to determine where your snapshots are stored.
* **Manage snapshots independently:** Access and filter snapshots as a first-class resource through the dedicated `/snapshots` top-level endpoint.
* **Query supported configurations:** Retrieve the supported MongoDB versions, their upgrade paths and lifecycle dates, and the instance templates available to Business edition clusters.
* **Search and filter resources:** Filter clusters by name, state, and edition, and snapshots by cluster ID (`filter.clusterId`), alongside standardized pagination across listing endpoints.

### Endpoints

The MongoDB v2 API is available with the following API endpoints.

| **Location**              | **Region** | **Endpoint**                          |
| ------------------------- | ---------- | ------------------------------------- |
| Worcester, United Kingdom | `gb-bhx`   | `https://mongodb.gb-bhx.ionos.com/v2` |
| Newark, United States     | `us-ewr`   | `https://mongodb.us-ewr.ionos.com/v2` |

To authenticate with the API, see [<mark style="color:blue;">Authentication</mark>](#tag/Authentication). To make your first API call, see [<mark style="color:blue;">Quick Start</mark>](#tag/Quick-Start).

### Features

* **Editions:** The `edition` property selects the cluster type and cannot be omitted.
  * `BUSINESS`: Sized through an instance template (`instanceTemplateId`) and an instance count (`instanceCount`). Retrieve the available templates with [<mark style="color:blue;">Retrieve all InstanceTemplates</mark>](#tag/InstanceTemplates/operation/instancetemplatesGet).
  * `ENTERPRISE`: Sized through a full `instances` configuration (`count`, `ram`, `cores`, and `storageSize`). Supports sharding and the BI Connector.
* **Replica sets and sharding:** A cluster has one primary and optional secondaries for high availability. On the Enterprise edition, `sharding.enabled` distributes data across 2 to 5 shards. When sharding is enabled, the instance `count` is the number of replicas per shard, and the cluster additionally runs three config servers that store the cluster metadata. Provide exactly three `instanceAddresses` for them, regardless of the instance count and the number of shards.
* **BI Connector:** On the Enterprise edition, `biConnectorEnabled` exposes the MongoDB BI Connector over the MySQL wire protocol on the fixed port `27015`, at the host `bi-connect.<mongo-host>`.
* **Point-in-Time Recovery:** Each snapshot retains the cluster's oplog. A restore replays the oplog up to `recoveryTargetDatetime`, so you can recover to any moment within the snapshot's recovery window, not only to the instant the snapshot was taken.
* **Ensure pattern:** Cluster updates use strict replacement logic through `PUT` endpoints. Provide the full resource object on every call. Fields not included in the payload reset to their defaults rather than retaining their previous values.

### Initial Database User

When you create a cluster, you provide credentials for one initial database user: `username`, `password`, and `database`. The password is write-only and is never returned in responses.

The initial user is not a root or full administrator user, but its permissions are close to it:

* It owns the database named in `credentials.database` (the `dbOwner` role).
* It can read, write, and administer every other database on the cluster, both existing and created later (the `readWriteAnyDatabase` and `dbAdminAnyDatabase` roles).

Omit `credentials` on a cluster update to leave the existing user unchanged. To create further users and databases, connect to the cluster and use standard MongoDB commands. The v2 API does not provide user management endpoints.

Some user names and database names are reserved for platform use and cannot be used for your own user or initial database.

### Rate Limiting

The MongoDB v2 API enforces rate limits. If a request exceeds the limit, the API returns HTTP `429 Too Many Requests`. Wait before you retry the request.

### Pagination

All list endpoints support offset-based pagination through two query parameters. The endpoints are: [<mark style="color:blue;">Retrieve all Clusters</mark>](#tag/Clusters/operation/clustersGet), [<mark style="color:blue;">Retrieve all Snapshots</mark>](#tag/Snapshots/operation/snapshotsGet), [<mark style="color:blue;">Retrieve all InstanceTemplates</mark>](#tag/InstanceTemplates/operation/instancetemplatesGet), [<mark style="color:blue;">Retrieve all SnapshotLocations</mark>](#tag/SnapshotLocations/operation/snapshotlocationsGet), and [<mark style="color:blue;">Retrieve all Versions</mark>](#tag/Versions/operation/versionsGet).

| **Parameter** | **Type** | **Default** | **Range**       | **Description**                                    |
| ------------- | -------- | ----------- | --------------- | -------------------------------------------------- |
| `offset`      | integer  | `0`         | ≥ 0             | The index of the first element to return.          |
| `limit`       | integer  | `100`       | from 1 to 1,000 | The maximum number of elements to return per page. |

To retrieve the next page, increment `offset` by the value of `limit`. Every list response also includes `total`, the total number of elements available, which you can use to display the size of the full list or to detect the last page.

### Benefits

* **Reduce operational overhead:** Managed provisioning, scaling, and snapshots let you focus on your application instead of infrastructure.
* **Protect data durability:** Snapshots with oplog retention and point-in-time recovery let you restore a cluster to any moment within the recovery window.
* **Maintain data residency compliance:** Explicit snapshot location management provides control over where cluster snapshots are stored.
* **Choose the right fit:** Use the Business edition for template-sized clusters, or the Enterprise edition for full control over resources, sharding, and the BI Connector.
* **Streamline cluster lifecycle management:** The idempotent Ensure pattern lets you apply full desired-state updates without tracking partial changes.


---

# 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/overview.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.
