Docs Menu

Read and Write with the Data API (Preview)

On this page

  • When to Use the Data API
  • Get Started
  • 1. Enable the Data API
  • 2. Create a Data API Key
  • 3. Send a Data API Request
  • Extended JSON Responses
  • Extended JSON Requests
  • Binary
  • Date
  • Decimal128
  • Double
  • Int64
  • Int32
  • ObjectId
  • Request Logs
  • Request Limitations
  • Billing

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"}

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.

Follow the steps below to set up the Data API and send your first requests.

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.

Note

You can enable or disable the Data API for a cluster at any time from the Data API screen.

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.

Important

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.

Tip

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.

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:

Tip

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.
  1. 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
    }
    }'
  2. 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" }
    }'
  3. 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" }
    }'

By default, the Data API encodes response body content in JSON. MongoDB stores data as BSON and uses MongoDB Extended JSON, or EJSON, to represent types that do not exist in the JSON format. To translate MongoDB EJSON data into JSON responses, the Data API translates fields into JSON values when possible and omits the values of EJSON fields that have no JSON equivalent.

The following table shows how JSON and EJSON can differ in responses from the Data API:

Type
EJSON Representation
JSON Representation
Array
[ <elements> ]
[ <elements> ]
Binary
{
"$binary": {
"base64": "DEADBEEF",
"subType": "04"
}
}
{
"Subtype": 4,
"Data": "DEADBEEF"
}
Date
{
"$date": {
"$numberLong": "1641954803067"
}
}
"2022-01-12T02:33:23.067Z"
Decimal128
{ "$numberDecimal": "9823.1297" }
"9823.1297"
Document
{ <content> }
{ <content> }
Double
{
"$numberDouble": "10.5"
}
10.5
Int32
{"$numberInt":"10"}
10
Int64
{"$numberLong":"50"}
50
MaxKey
{ "$maxKey": 1 }
{}
MinKey
{ "$minKey": 1 }
{}
ObjectId
{
"$oid":"5d505646cf6d4fe581014ab2"
}
"5d505646cf6d4fe581014ab2"
Regular Expression
{
"$regularExpression": {
"pattern":"^H",
"options":"i"
}
}
{
"Pattern": "^H",
"Options": "i"
},
Timestamp
{
"$timestamp": {
"t":1565545664,
"i":1
}
}
{
"T": 1565545664,
"I": 1
}
Important

EJSON values with no JSON equivalent, such as MinKey and MaxKey, translate to an empty document ({}).

To avoid any field value translations or omissions, configure the Data API to respond with EJSON. Use the Accept header to control the response type:

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.

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"
}
}
}
}'

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" } }
}
}'

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" }
}
}'

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" }
}
}'

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" }
}
}'

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" }
}
}'

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" }
}
}'

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.

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.

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.
←  Atlas Administration API Error CodesData API Resources →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.