MongoDB Atlas Data API (v1)

Download OpenAPI specification:Download

A fully-managed API to read, write, and aggregate data in MongoDB Atlas. The Data API is powered by serverless Atlas Functions and secured with user authentication and role-based permissions. To learn more about the Data API, see Atlas Data API.

Set Up the Data API

Before you can use the Data API, you must enable and configure it in an Atlas App Services App. The configuration controls how the App's users authenticate, authorize requests, and interact with the API.

To learn how to start using the Data API in your App, see Set up the Data API.

Authenticate Requests

Your Data API configuration in App Services controls how users authenticate their API requests. In most cases, you will use Application authentication, which lets users log in with one of the App's authentication providers. Users can either provide their login credentials directly in every request or provide a reusable access token for an authenticated session.

To learn more, see Authenticate Data API Requests.

Find One Document

Find a single document that matches a query.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter required	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.
	object A MongoDB projection for matched documents returned by the operation.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"text": "Do the dishes"
},
"projection": {"status": 1,
"text": 1
}
}

Response samples

200
400
401

Content type

application/json

{"document": {"_id": "6193504e1be4ab27791c8133",
"status": "open",
"text": "Do the dishes"
}
}

Find Documents

Find multiple documents that match a query.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter required	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.
	object A MongoDB projection for matched documents returned by the operation.
sort	object A MongoDB sort expression that indicates sorted field names and directions.
limit	number The maximum number of matching documents to include the in the response.
skip	number The number of matching documents to omit from the response.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"status": "complete"
},
"projection": {"text": 1,
"completedAt": 1
},
"sort": {"completedAt": 1
},
"limit": 10
}

Response samples

200
400
401

Content type

application/json

{"documents": [{"_id": "6193504e1be4ab27791c8133",
"text": "Do the dishes",
"completedAt": "2022-05-16T20:22:01.104Z"
},
{"_id": "6194604e1d38dc33792d8257",
"text": "Feed the dog",
"completedAt": "2022-05-17T05:12:42.828Z"
}
]
}

Insert One Document

Insert a single document into a collection.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
document required	object A document to insert into the collection.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"document": {"status": "open${{ env.BUNDLED_SPEC_FILEPATH }}",
"text": "Do the dishes"
}
}

Response samples

200
400
401

Content type

application/json

{"insertedId": "6193504e1be4ab27791c8133"
}

Insert Documents

Insert multiple documents into a collection.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
documents required	Array of objects A list of documents to insert into the collection.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"documents": [{"status": "open",
"text": "Mop the floor"
},
{"status": "open",
"text": "Clean the windows"
}
]
}

Response samples

200
400
401

Content type

application/json

{"insertedIds": ["61935189ec53247016a623c9",
"61935189ec53247016a623ca"
]
}

Update One Document

Update a single document in a collection.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter required	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.
update required	object A MongoDB update expression to apply to matching documents. For a list of all update operators that the Data API supports, see Update Operators.
upsert	boolean Default: false When `true`, if the update filter does not match any existing documents, then insert a new document based on the filter and the specified update operation.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"_id": {"$oid": "642f1bb5cee4111898828bf6"
}
},
"update": {"$set": {"status": "complete"
}
},
"upsert": false
}

Response samples

200
400
401

Content type

application/json

{"matchedCount": 1,
"modifiedCount": 1
}

Update Documents

Update multiple documents in a collection.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter required	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.
update required	object A MongoDB update expression to apply to matching documents. For a list of all update operators that the Data API supports, see Update Operators.
upsert	boolean Default: false When `true`, if the update filter does not match any existing documents, then insert a new document based on the filter and the specified update operation.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"status": "open"
},
"update": {"$set": {"status": "complete"
}
}
}

Response samples

200
400
401

Content type

application/json

{"matchedCount": 12,
"modifiedCount": 12
}

Delete One Document

Delete a single document that matches a query.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"text": "Do the dishes"
}
}

Response samples

200
400
401

Content type

application/json

{"deletedCount": 1
}

Delete Documents

Delete multiple documents that match a query.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
filter	object A MongoDB query filter that matches documents. For a list of all query operators that the Data API supports, see Query Operators.

Responses

Request samples

Payload
cURL

Content type

application/json

{"dataSource": "mongodb-atlas",
"database": "todo",
"collection": "tasks",
"filter": {"status": "complete"
}
}

Response samples

200
400
401

Content type

application/json

{"deletedCount": 12
}

Aggregate Documents

Run an aggregation pipeline.

Authorizations:

AccessToken(EmailPassword) ApiKeyCustomJwt

Request Body schema:
application/json

dataSource required	string The name of a linked MongoDB Atlas data source. This is commonly `"mongodb-atlas"` though it may be different in your App if you chose a different name when you created the data source.
database required	string The name of a database in the specified data source.
collection required	string The name of a collection in the specified database.
pipeline required	Array of objects An array of aggregation stages.

Responses

Request samples

Payload
cURL

Content type

application/json

[{"$groupBy": {"_id": "$status",
"count": {"$sum": 1
},
"tasks": {"$push": "$text"
}
}
},
{"$sort": {"count": 1
}
}
]

Response samples

200
400
401

Content type

application/json

[{"$groupBy": {"_id": "$status",
"count": {"$sum": 1
},
"tasks": {"$push": "$text"
}
}
},
{"$sort": {"count": 1
}
}
]

MongoDB Atlas Data API (v1)

Set Up the Data API

Authenticate Requests

Find One Document

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Find Documents

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Insert One Document

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Insert Documents

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Update One Document

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Update Documents

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Delete One Document

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Delete Documents

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Aggregate Documents

Authorizations:

Request Body schema: application/jsonapplication/ejsonapplication/json

Responses

Request samples

Response samples

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json

Request Body schema:
application/json