Docs Home → Atlas App Services
Data API Endpoints
On this page
- When to Use the Data API
- Base URL
- Set Up the Data API
- Authentication
- Authorization
- Response Type
- Access Permissions
- API Versions
- Call a Data API Endpoint
- Choose an API Version
- Specify the Request Data Format
- Choose a Response Data Format
- Authenticate the Request
- Authorize the Request
- Endpoints
- Find a Single Document
- Find Multiple Documents
- Insert a Single Document
- Insert Multiple Documents
- Update a Single Document
- Update Multiple Documents
- Replace a Single Document
- Delete a Single Document
- Delete Multiple Documents
- Run an Aggregation Pipeline
- Error Codes
The Data API lets you securely read and write data using standard HTTPS requests. The API includes automatically generated endpoints that each represent a MongoDB operation. You can use the endpoints to create, read, update, delete, and aggregate documents in a MongoDB data source.
For example, this POST request stores a
document in a linked cluster by calling the insertOne
endpoint:
curl --request POST \ 'https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6' \ --data-raw '{ "dataSource": "mongodb-atlas", "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 with any app or service that supports HTTPS requests. For example, you might:
call the API from a serverless edge function
query Atlas from a mobile application
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.
Base URL
The Data API endpoints in an app share a base URL. The URL uses your App ID to uniquely point to your app and specifies which version of the Data API to call. Each endpoint has a unique URL formed by appending the endpoint's route to your app's base URL.
Globally deployed apps use the following format:
https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
Endpoints in a locally deployed app use a base URL specific to the app's
deployment region (e.g. us-east-1.aws
):
https://<Region>.<Cloud>.data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
Set Up the Data API
You can configure the Data API for your app from the App Services UI or by deploying configuration files with Realm CLI:
Authentication
Data API endpoints run in the context of a specific user, which allows your app to enforce rules and validate document schemas for each request.
By default, endpoints use Application Authentication, which requires each request to include credentials for one of your application users, like an API key or JWT. You can also configure other custom authentication schemes to fit your application's needs.
For examples of how to authenticate requests, see Authenticate Data API Requests.
Authorization
You can require authenticated users to provide additional authorization information in each request. You define the authorization scheme for all generated Data API endpoints in your Data API configuration.
Endpoints natively support a set of built-in authorization schemes that use a secret string to prove that the request is authorized. You can also define a custom authorization scheme that you can use together with or instead of the built-in schemes.
Built-In Authorization Schemes
Endpoints support the following built-in authorization schemes:
Custom Authorization Schemes
You can define a custom authorization expression to
determine if an incoming authenticated request is allowed to run. The
expression is evaluated for each request and must evaluate to true
to allow the request. If the expression evaluates to false
, the
request is not authorized and fails with an error. Requests that fail
authorization are not counted toward your App's billed usage.
Authorization expressions can use variables like
%%user
to authorize based on the calling user's data
or %%request
to make decisions based on the specifics
of each incoming request.
To define a custom authorization scheme, specify the expression in your app's Data API configuration:
{ ..., "can_evaluate": { "%%request.headers.x-secret-key": "my-secret" } }
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.
Access Permissions
The Data API uses your app's data access rules to determine if a user can read and write data. To allow Data API requests to access a specific collection, you must first define rules for the collection.
You can also set up an IP Access List for additional security.
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
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.
Choose an API Version
Data API requests specify which version of the API to use in the request URL. A request can specify any version that is enabled for your app.
https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
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
If an endpoint is configured to use Application Authentication then you must include a valid user access token or login credentials with every request.
In general, bearer authentication with an access token has higher throughput and is more secure than credential headers. Use an access token instead of credential headers when possible. The token lets you run multiple requests without re-authenticating the user. It also lets you send requests from a web browser that enforces CORS.
To use an access token, first authenticate the user through an App Services authentication provider. Then, get the access token returned from App Services and include it in the request's Authorization header using a Bearer token scheme. For more information on how to acquire and use an access token, see Bearer Token Authentication.
curl -X POST 'https://data.mongodb-api.com/app/<AppID>/endpoint/data/v1/action/find' \ --header 'Authorization: Bearer <AccessToken>' \ --header 'Content-Type: application/json' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "sample_mflix", "collection": "movies", "filter": { "title": "The Matrix" } }'
Alternatively, you can include valid login credentials for the user in the request headers.
Important
Don't Use API Keys in User-Facing Clients
If you're authenticating from a browser or another user-facing client application, avoid using an API key to log in. Instead, use another authentication provider that takes user-provided credentials. Never store API keys or other sensitive credentials locally.
Authorize the Request
Depending on your Data API authorization configuration, your requests may need to include additional authorization information.
Endpoints
Find a Single Document
Endpoint
POST /action/findOne
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/findOne' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "text": "Do the dishes" } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": <query filter>, "projection": <projection> }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Optional | A MongoDB Query Filter.
The If you do not specify a | {} |
---|---|---|---|---|
projection | object | Optional | A MongoDB Query Projection.
Depending on the projection, the returned document will either
omit specific fields or include only specified fields or values | {} |
Response
The findOne
action returns the matched document in the document
field:
{ "document": { "_id": "6193504e1be4ab27791c8133", "test": "foo" } }
If the action does not match any documents, the document
field is
null
:
{ "document": null }
Find Multiple Documents
Endpoint
POST /action/find
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/find' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "status": "complete" }, "sort": { "completedAt": 1 }, "limit": 10 }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": <query filter>, "projection": <projection>, "sort": <sort expression>, "limit": <number>, "skip": <number> }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Optional | A MongoDB Query Filter. The
If you do not specify a If the filter matches more documents than the specified
| {} |
---|---|---|---|---|
projection | object | Optional | A MongoDB Query Projection.
Depending on the projection, the returned documents either omit
specific fields or include only specified fields and values. | {} |
sort | object | Optional | A MongoDB Sort Expression.
Matched documents are returned in ascending or descending order
of the fields specified in the expression. | {} |
limit | number | Optional | The maximum number of matched documents to include in the
returned result set. Each request may return up to 50,000
documents. | 1000 |
skip | number | Optional | The number of matched documents to skip before adding matched
documents to the result set. | 0 |
Response
The find
action returns an array of matched document in the
documents
field:
{ "documents": [ { "_id": "6193504e1be4ab27791c8133", ... }, { "_id": "6194604e1d38dc33792d8257", ... } ] }
If the action does not match any documents, the documents
field is
an empty array:
{ "documents": [] }
Insert a Single Document
Endpoint
POST /action/insertOne
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/insertOne' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "document": { "status": "open", "text": "Do the dishes" } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "document": { ... }, }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
document | object | Required | An EJSON document
to insert into the collection. |
---|
Response
The insertOne
action returns the _id
value of the inserted
document as a string in the insertedId
field:
Insert Multiple Documents
Endpoint
POST /action/insertMany
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/insertMany' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "documents": [ { "status": "open", "text": "Mop the floor" }, { "status": "open", "text": "Clean the windows" } ] }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "documents": [{ ... }, ...] }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
documents | array of objects | Required | An array of one or more EJSON
documents to insert into the collection. |
---|
Response
The insertMany
action returns the _id
values of all inserted
documents as an array of strings in the insertedIds
field:
{ "insertedIds": ["61935189ec53247016a623c9", "61935189ec53247016a623ca"] }
Update a Single Document
Endpoint
POST /action/updateOne
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/updateOne' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "_id": { "$oid": "6193ebd53821e5ec5b4f6c3b" } }, "update": { "$set": { "status": "complete", "completedAt": { "$date": { "$numberLong": "1637083942954" } } } } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": { ... }, "update": { ... }, "upsert": true|false }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Required | A MongoDB Query Filter.
The updateOne action modifies the first document in the
collection that matches this filter. | |
---|---|---|---|---|
update | object | Required | A MongoDB Update Expression
that specifies how to modify the matched document. | |
upsert | boolean | Optional | The upsert flag only applies if no documents match the
specified filter . If true , the updateOne action
inserts a new document that matches the filter with the specified
update applied to it. | false |
Response
The updateOne
action returns:
the number of documents that the filter matched in the
matchedCount
fieldthe number of matching documents that were updated in the
modifiedCount
field
{ "matchedCount": 1, "modifiedCount": 1 }
If upsert
is set to true
and no documents match the filter, the
action returns the _id
value of the inserted document as a string in
the upsertedId
field:
{ "matchedCount": 0, "modifiedCount": 0, "upsertedId": "619353593821e5ec5b0f8944" }
Update Multiple Documents
Endpoint
POST /action/updateMany
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/updateMany' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "status": "open" }, "update": { "$set": { "status": "complete", "completedAt": { "$date": { "$numberLong": "1637083942954" } } } } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": { ... }, "update": { ... }, "upsert": true|false }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Required | A MongoDB Query Filter.
The updateMany action modifies all documents in the
collection that match this filter. | |
---|---|---|---|---|
update | object | Required | A MongoDB Update Expression
that specifies how to modify matched documents. | |
upsert | boolean | Optional | The upsert flag only applies if no documents match the
specified filter . If true , the updateMany action
inserts a new document that matches the filter with the specified
update applied to it. | false |
Response
The updateMany
action returns:
the number of documents that the filter matched in the
matchedCount
fieldthe number of matching documents that were updated in the
modifiedCount
field
{ "matchedCount": 12, "modifiedCount": 12 }
If upsert
is set to true
and no documents match the filter, the
action returns the _id
value of the inserted document as a string in
the upsertedId
field:
{ "matchedCount": 0, "modifiedCount": 0, "upsertedId": "619353593821e5ec5b0f8944" }
Replace a Single Document
Endpoint
POST /action/replaceOne
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/replaceOne' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "text": "Call Jessica" }, "replacement": { "status": "open", "text": "Call Amy" } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": { ... }, "replacement": { ... }, "upsert": true|false }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Required | A MongoDB Query Filter.
The replaceOne action overwrites the first document in the
collection that matches this filter. | |
---|---|---|---|---|
replacement | object | Required | An EJSON document
that overwrites the matched document. | |
upsert | boolean | Optional | The upsert flag only applies if no documents match the
specified filter . If true , the replaceOne action
inserts the replacement document. | false |
Response
The replaceOne
action returns:
the number of documents that the filter matched in the
matchedCount
fieldthe number of matching documents that were replaced in the
modifiedCount
field
{ "matchedCount": 1, "modifiedCount": 1 }
If upsert
is set to true
and no documents match the filter, the
action returns the _id
value of the inserted document as a string in
the upsertedId
field:
{ "matchedCount": 0, "modifiedCount": 0, "upsertedId": "619353593821e5ec5b0f8944" }
Delete a Single Document
Endpoint
POST /action/deleteOne
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/deleteOne' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "_id": { "$oid": "6193ebd53821e5ec5b4f6c3b" } } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": { ... } }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Required | A MongoDB Query Filter.
The deleteOne action deletes the first document in the
collection that matches this filter. |
---|
Response
The deleteOne
action returns the number of deleted documents in the
deletedCount
field:
{ "deletedCount": 1 }
Delete Multiple Documents
Endpoint
POST /action/deleteMany
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/deleteMany' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "filter": { "status": "complete" } }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "filter": { ... } }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
filter | object | Required | A MongoDB Query Filter.
The deleteMany action deletes all documents in the collection
that match this filter. |
---|
Response
The deleteMany
action returns the number of deleted documents in the
deletedCount
field:
{ "deletedCount": 42 }
Run an Aggregation Pipeline
Endpoint
POST /action/aggregate
Example
curl --request POST \ 'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/aggregate' \ --header 'Content-Type: application/json' \ --header 'apiKey: <API Key>' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "tasks", "pipeline": [ { "$group": { "_id": "$status", "count": { "$sum": 1 }, "text": { "$push": "$text" } } }, { "$sort": { "count": 1 } } ] }'
Request Body
{ "dataSource": "<data source name>", "database": "<database name>", "collection": "<collection name>", "pipeline": [<aggregation pipeline>] }
Name | Type | Necessity | Description | Default |
---|---|---|---|---|
dataSource | string | Required | The name of the linked data source. | |
database | string | Required | The name of the database. | |
collection | string | Required | The name of the collection. |
pipeline | array of objects | Required |
---|
Response
The aggregate
action returns the result set of the final stage of
the pipeline as an array of documents in the documents
field:
{ "documents": [{ ... }, ...] }
Error Codes
Code | Description |
---|---|
400 | Bad request The request was invalid. This might mean:
|
401 | Unauthorized The request did not include an authorized and enabled API Key. Ensure that your API Key is enabled for the cluster. |
404 | Not found The request was sent to an endpoint that does not exist. |
500s | Server errors The Data API encountered an internal error and could not complete the request. |