Read and Write with the Data API

The MongoDB Atlas Data API lets you read and write data in Atlas with standard HTTPS requests. To use the Data API, all you need is an HTTPS client and a valid API key.

Clients send requests to specific endpoints, which each represent a MongoDB operation. The API includes endpoints that create, read, update, delete, and aggregate documents in your cluster. Requests specify a collection and include operation-specific parameters like a query filter or update description. Additionally, all incoming requests must include a Data API key to authenticate the calling user.

For each request, the Data API authenticates the user and checks the cluster's read/write permissions. If the user's request is authorized, then the API validates the request, runs the corresponding database operation, and returns the result 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-abcde/endpoint/data/v1/action/insertOne' \
  --header 'Content-Type: application/json' \
  --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.

How the Data API Works

The Data API is not a direct connection to your database. Instead, it routes requests through a fully-managed middleware layer, called Atlas App Services, that sits between your cluster and client apps. This layer handles user authentication and enforces data access rules to ensure that your data is secure.

You can quickly set up and access the Data API through Atlas, which creates and manages an App Services app for you. Atlas supports API key authentication with several basic permissions models.

You can also define more complex API access permissions and custom endpoints by accessing the managed Atlas Data API app directly or enabling the API in your own app.

To learn more about App Services and how the Data API works, see Data API (App Services).

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.

Note

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.

Important

Data API keys are not the same as the programmatic API keys used to access the Atlas and App Services 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.

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:

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.

Insert a test document:

curl --request POST \
  'https://data.mongodb-api.com/app/<Data API App ID>/endpoint/data/v1/action/insertOne' \
  --header 'Content-Type: application/json' \
  --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/v1/action/findOne' \
  --header 'Content-Type: application/json' \
  --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/v1/action/deleteOne' \
  --header 'Content-Type: application/json' \
  --header 'api-key: <Data API Key>' \
  --data-raw '{
      "dataSource": "<cluster name>",
      "database": "learn-data-api",
      "collection": "people",
      "filter": { "name": "John Sample" }
  }'

Configure the Data API

You can configure your API deployment and how users interact with the API.

API Versions

The Data API uses a built-in versioning scheme to upgrade endpoints over time while maintaining backwards compatibility. Incoming requests can specify which version of an endpoint to use in the request URL and the Data API can serve any version that you have enabled.

You must enable a new version before users can call endpoints with that version. You can always enable the most recent Data API version. However, you cannot enable an older version after a newer version has been released.

The following versions are currently supported:

beta
v1

Data Access Permissions

The Atlas Data API allows you to define cluster-level read/write permissions that apply to all incoming requests. You can define one of the following for each cluster:

Read and Write: Requests can read all data and can insert, modify, or delete data in any collection.
Read Only: Requests can read all data in any collection but cannot write any data.
No Access: Requests can't read or write any data in any collection.

For more complex permissions, you can define custom data access rules in the managed Atlas Data API app.

Authentication and API Keys

The Atlas Data API supports user authentication with API keys. Incoming requests must include an API key in a request header. You can create up to 100 Data API keys.

To allow users to authenticate requests with another method, like a username and password or a JSON web token, you can enable additional authentication providers in the managed Atlas Data API app.

Deployment Models & Regions

The App Services layer that runs the Data API processes requests on managed servers hosted in deployment regions around the world. You can control where you deploy your Data API and process requests using one of two deployment models:

Global deployment hosts your API on servers in every supported region across the world. The API automatically routes and processes incoming requests to the server that's nearest to the requesting user.
Local deployment hosts your API servers in one specific deployment region in AWS or Azure. The API processes all incoming requests in the local region.
For a list of supported regions, see Deployment Models & Regions in the App Services docs.

Response Type

Endpoints can return data in one of two data formats, either JSON or EJSON.

By default, endpoints return JSON, which is a standard data format that is widely supported modern langauges and platforms. However, JSON cannot represent every data type that you can store in MongoDB and loses type information for some data types.

You can also configure endpoints to return EJSON, which uses structured JSON objects to fully represent the types that MongoDB supports. This preserves type information in responses but requires that your application understands how to parse and use EJSON.

Tip

The official MongoDB drivers include methods for working with EJSON. You can also download a standalone parser like bson on npm.

Call a Data API Endpoint

You can call a Data API endpoint from any standard HTTP client. Each request can include configuration headers and arguments in the request body.

Specify the Request Data Format

Data API requests must include a Content-Type header to specify the data format used in the request body.

Use Content-Type: application/json to represent standard JSON types in a Data API request body.
Use Content-Type: application/ejson to represent standard JSON types and additional EJSON types in a Data API request body.

Choose a Response Data Format

A request can include an Accept header to request a specific data format for the response body, either JSON or EJSON. If a request does not include a valid Accept header, the response uses the data format specified in your Data API configuration.

Authenticate the Request

To keep your data secure and correct, generated Data API endpoints always run in the context of a specific, registered user and automatically enforce your app's rules and schemas. Incoming requests must include one or more headers that contain valid user credentials for one of the following enabled authentication providers:

Data Formats

MongoDB stores data in a format called BSON, which is similar to a JSON object in structure but supports additional data types and uses a binary encoding. BSON is efficient for computers but is not human readable so you can't work with it directly.

Instead, the Data API uses two formats to represent data in requests and responses:

The JSON format uses standard types that any tool can parse and understand. However, JSON cannot represent all BSON types so JSON responses may lose type information for some fields. For example, BSON has distinct types for 32-bit integers and 64-bit floats but a JSON response represents both as a number.
The EJSON format, short for MongoDB Extended JSON, is a superset of standard JSON that uses structured fields to represent BSON data that don't have corresponding JSON types. This fully represents your data but requires your client to understand how to work with EJSON.

Example

The following document shows BSON types represented in JSON and EJSON:

The following table compares the JSON and EJSON representations of each supported type:

Type

EJSON

JSON

Array

[ <elements> ]

[ <elements> ]

Binary

{
   "$binary": {
      "base64": "e67803a39588be8a95731a21e27d7391",
      "subType": "05"
   }
}

{
   "Subtype": 5,
   "Data": "e67803a39588be8a95731a21e27d7391"
}

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

Int64

{"$numberLong":"50"}

MaxKey

{ "$maxKey": 1 }

{}

No JSON equivalent

MinKey

{ "$minKey": 1 }

{}

No JSON equivalent

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
}

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.

Request Traffic

The Data API limits request traffic to 5,000 concurrent requests. Any requests made beyond this limit return an HTTP response status code of 429 - Too Many Requests. You can request a higher limit by filing a support ticket.

Billing

The Data API has usage-based pricing measured by the underlying App Services application. For details, see App Services 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 Codes Data API Resources →