Data API for Azure Cosmos DB for MongoDB vCore (Preview)

2025-06-25

The Data API for Azure Cosmos DB for MongoDB vCore is an https interface that allows developers to access and interact with their MongoDB vCore data without needing a database driver. It simplifies data operations by enabling control plane and aggregation operations through HTTP requests. This API is ideal for web applications, providing secure and scalable access to MongoDB vCore databases.

Enabling Data API on MongoDB vCore

You can enable or disable this feature using the Azure portal, Azure CLI or an ARM template.

Steps to enable Data API on Azure portal

Go to Azure portal
- portal.azure.com
Go to your vCore-based Azure Cosmos DB for MongoDB cluster
Open the 'Features' blade
Click on 'Data API'
Click on 'Enable'
Verify the result
- Your 'Features' blade should now display 'Data API' as 'On'.

Steps to enable Data API on vCore cluster via ARM template

Get connection string:
- Obtain the connection string of your vCore cluster from the Azure portal.
Retrieve authentication token:
- Run the following commands in Windows PowerShell:
```
az login
az account get-access-token --resource-type arm
```
Send PATCH request:
- Use the connection string from the Azure portal and send a PATCH request with:
  - Authentication Token: Use the token retrieved from PowerShell.
  - Body:
```
{
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}
```
Verify result:
- Ensure the response payload includes "dataApi": {"mode": "Enabled"}.
- If you encounter the error "Data API isn't supported on this cluster," note that only newly provisioned clusters support Data API.

Update MongoDB vCore cluster configuration

Request

Method: PATCH
Endpoint: https://eastus2euap.management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.DocumentDB/mongoClusters/<ClusterName>?api-version=2024-10-01-preview

Request body

{
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}

Obtain connection string

To obtain the connection string for your MongoDB vCore cluster, follow these steps:

Navigate to the MongoDB vCore cluster that you created.
Go to Settings and select Connection Strings.
Copy the Data API endpoint provided.

How to use Data API

Let's explore the supported operations, how to use the Data API.

Aggregate

Use this command to perform an aggregation operation on a collection.

curl {cluster-name}.data.mongocluster.cosmos.azure.com:443/data/v1/action/aggregate -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection", "pipeline" : [{"$limit" : 500}]}' --user "{username}:{password}"

{ "documents" : [ { "_id" : { "$oid" : "680957492551581200c73bf8" }, "name" : "Sample Document", "createdAt" : { "$date" : { "$numberLong" : "1745442633506" } }, "tags" : [ "test", "mongo", "sample" ] } ] }

List databases

List all databases in the specified MongoDB vCore cluster.

curl {cluster-name}.data.global.mongocluster.cosmos.azure.com:443/data/v1/action/listDatabases -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{}' --user "{username}:{password}"

{ "databases" : [ { "name" : "testDB", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false }, { "name" : "test", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false } ], "totalSize" : { "$numberInt" : "0" }, "ok" : { "$numberDouble" : "1.0" } }

List collections

List all collections within a specific database.

curl {cluster-name}.data.global.mongocluster.cosmos.azure.com:443/data/v1/action/listCollections -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database": "newDB"}' --user "{username}:{password}"

{ "collections" : [ { "name" : "testCollection", "type" : "collection", "options" : {  }, "info" : { "readOnly" : false, "uuid" : { "$binary" : { "base64" : "mNh96KepTm+NtLtALGxDiw==", "subType" : "04" } } }, "idIndex" : { "v" : { "$numberInt" : "2" }, "name" : "_id_", "key" : { "_id" : { "$numberInt" : "1" } } } } ] }

Get schema

Retrieve the schema details of a specific database.

Here's the formatted version for your .md file:

curl {cluster-name}.data.mongocluster.cosmos.azure.com:443/data/v1/action/getSchema -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection"}' --user "{username}:{password}"

{ "_id" : { "bsonType" : "objectId" }, "name" : { "bsonType" : "string" }, "createdAt" : { "bsonType" : "date" }, "tags" : { "bsonType" : "array" } }

Limitations

Data API works on newly created MongoDB vCore cluster.
Data API doesn't support access using reusable access token.
Only supports data plane aggregation and limited control plane actions.

Share via