Read and Write with the Data API (Preview)
On this page
The MongoDB Atlas Data API lets you read and write data in Atlas with standard HTTPS requests. The API includes endpoints that create, read, update, delete, and aggregate documents in your cluster. To use the Data API, all you need is an HTTPS client and a valid API key.
The Data API is not a direct connection to your database. Instead, the API is a fully-managed middleware service that sits between your cluster and client apps. Clients send requests to specific endpoints, which each represent a MongoDB operation. For each request, the Data API authorizes the request, decodes and runs the database operation, and then returns the results of the operation in an HTTPS response.
For example, this POST request stores a
document in Atlas by calling the insertOne endpoint:
curl --request POST \ 'https://data.mongodb-api.com/app/data-xtest/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6' \ --data-raw '{ "dataSource": "Cluster0", "database": "learn-data-api", "collection": "hello", "document": { "text": "Hello from the Data API!", } }'
{"insertedId":"5f1a785e1536b6e6992fd588"}
When to Use the Data API
You can use the Data API to integrate Atlas into any apps and services that support HTTPS requests. For example, you might:
- call the API from a serverless edge function
- access test data and log events in a CI/CD workflow
- integrate Atlas into a federated API gateway
- connect from an environment not currently supported via a MongoDB Driver or Realm SDK
An operation called through an API endpoint will likely take longer than the corresponding MongoDB operation called through a connected MongoDB Driver. For high-load use-cases and latency sensitive applications, we recommend connecting directly to your database with a MongoDB driver. To learn more, visit the MongoDB Drivers documentation.
Get Started
Follow the steps below to set up the Data API and send your first requests.
1. Enable the Data API
The Data API is disabled by default. To use the API, you need to turn it on in the Atlas UI for one or more clusters.
Click Data API in the left navigation menu. On the following screen, select one or more clusters that you want to enable the API on from the dropdown menu and then click Enable the Data API.
You can enable or disable the Data API for a cluster at any time from the Data API screen.
2. Create a Data API Key
The Data API uses project-level API keys to manage access and prevent unauthorized requests. Every request must include a valid Data API key.
A Data API key grants full read and write access every collection in a cluster and can access any enabled cluster in the project.
Data API keys are not the same as the programmatic API keys used to access the Atlas and Realm Administration APIs.
Click Create API Key, enter a unique name for the new key, and then click Create API Key.
You can now see and copy your new API key for the first and only time. Once you close the modal, Atlas will never expose the value again.
Copy the new API key and store it somewhere safe where you can reference it later. Data API keys are sensitive, so make sure not to hardcode them directly into user-facing apps or commit them to version control.
You can delete a Data API key at any time. Any request that includes a deleted key will fail. You might delete a key to prevent an existing client from continuing to use the API or if you accidentally expose the key and need to replace it.
3. Send a Data API Request
You include your Data API key when you call action endpoints that read and write documents in MongoDB. For a list of all available actions & endpoints, see Data API Resources.
You can run the following commands in a shell to make sure everything works and then start exploring:
Make sure to replace placeholder values before you run each request:
<Data API App ID>: Your Data API App ID, which you can find in the URL Endpoint section of the UI.<Data API key>: The Data API key you just created.<cluster name>: The name of a cluster with the Data API enabled.
Insert a test document:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "learn-data-api", "collection": "people", "document": { "name": "John Sample", "age": 42 } }' Then, find the test document that you just inserted:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/findOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "learn-data-api", "collection": "people", "filter": { "name": "John Sample" } }' Finally, delete the test document:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/deleteOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "learn-data-api", "collection": "people", "filter": { "name": "John Sample" } }'
Extended JSON
The Data API uses canonical MongoDB Extended JSON to encode BSON data types in request bodies.
The following sections demonstrate how to define EJSON types in your requests.
Binary
To specify a binary value, use $binary with the value encoded in
Base64 and a BSON subtype:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "data": { "$binary": { "base64": "46d989eaf0bde5258029534bc2dc2089", "subType": "5" } } } }'
Date
To specify a date, use $date with the UNIX timestamp in
milliseconds as a 64-bit integer:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "createdAt": { "$date": { "$numberLong": "1638551310749" } } } }'
Decimal128
To specify a 128-bit decimal, use $numberDecimal with the decimal
value as a string:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "accountBalance": { "$numberDecimal": "128452.420523" } } }'
Double
To specify a 64-bit signed floating point value (commonly referred to as
a "double"), use $numberDouble with the integer value as a string:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "temperatureCelsius": { "$numberDouble": "23.847" } } }'
Int64
To specify a 64-bit signed integer value, use $numberLong with the
integer value as a string:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "population": { "$numberLong": "8047923148" } } }'
Int32
To specify a 32-bit signed integer value, use $numberInt with the
integer value as a string:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "coins": { "$numberInt": "2147483647" } } }'
ObjectId
To specify an ObjectId value, use $oid with the ID as a byte string:
curl --request POST \ 'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/beta/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Access-Control-Request-Headers: *' \ --header 'api-key: <Data API Key>' \ --data-raw '{ "dataSource": "<cluster name>", "database": "<database name>", "collection": "<collection name>", "document": { "_id": { "$oid": "61f02ea3af3561e283d06b91" } } }'
Request Logs
The Data API logs all requests and stores the logs for 30 days.
You can view them on the Data API screen in the Logs tab.
Request Limitations
The Data API enforces the following limitations on all requests:
- Incoming requests may not exceed 18 MB.
- Response body content may not exceed 16 MB.
- Request processing time may not exceed 90 seconds.
Billing
The Data API uses the same usage-based pricing as MongoDB Realm applications. For details, see MongoDB Realm Billing.
Data API usage is billed based on the following dimensions:
- Requests: Every action adds one request to your billed total regardless of whether or not the action is successful.
- Compute: Every action bills for time and memory that the server uses to process the action. The exact usage depends on your workload.
- Data Transfer: Every action bills for data returned to the caller in the response. The response may include the result set of the action or metadata that describes the result of the action.