Find Documents

POST /action/find

Access token Email & Password Api key Custom jwt

Find multiple documents that match a query.

Body

dataSource string Required

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 string Required

The name of a database in the specified data source.
collection string Required

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.
projection object

A MongoDB projection for matched documents returned by the operation.
Hide projection attribute Show projection attribute object
- * number Additional properties
  
  Values are 0 or 1.
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.

Body

dataSource string Required

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 string Required

The name of a database in the specified data source.
collection string Required

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.
projection object

A MongoDB projection for matched documents returned by the operation.
Hide projection attribute Show projection attribute object
- * number Additional properties
  
  Values are 0 or 1.
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

200

application/json

application/json application/ejson

Found
Hide response attribute Show response attribute object
- documents array[object]
  
  A list of documents that match the specified filter.
Hide response attribute Show response attribute object
- documents array[object]
  
  A list of documents that match the specified filter.
400 application/json

The request was malformed or incomplete.
One of:
ErrorNoAuthenticationSpecified object ErrorMissingAuthenticationParameter object
Indicates that the request did not include any authentication credentials.

Hide attributes Show attributes

error string

A message that describes the error.

Value is no authentication methods were specified.

error_code string

The error type.

Value is InvalidParameter.

link string

A link to a log entry for the failed operation.
Indicates that an authentication parameter is missing from the request body or headers. For example, the request might include an email header but no corresponding password header.

Hide attributes Show attributes

error string

A message that describes the error.

Value is must specify some form of authentication (either email+password, api-key, or jwt) in the request header or body.

error_code string

The error type.

Value is MissingParameter.

link string

A link to a log entry for the failed operation.
401 application/json

The authenticated user does not have permission to access this endpoint.
Hide response attributes Show response attributes object
Indicates that no user matched the provided authentication credentials.
- error string
  
  A message that describes the error.
  
  Value is invalid session: error finding user for endpoint.
- error_code string
  
  The error type.
  
  Value is InvalidSession.
- link string
  
  A link to a log entry for the failed operation.

POST /action/find

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/find" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "status": "complete"
    },
    "sort": { "completedAt": 1 },
    "limit": 10
  }'

Request example

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

Request example

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

Response examples (200)

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

Response examples (200)

{
  "documents": [
    {
      "_id": {
        "$oid": "6193504e1be4ab27791c8133"
      },
      "text": "Do the dishes",
      "completedAt": {
        "$date": {
          "$numberLong": "1652732521104"
        }
      }
    },
    {
      "_id": {
        "$oid": "6194604e1d38dc33792d8257"
      },
      "text": "Feed the dog",
      "completedAt": {
        "$date": {
          "$numberLong": "1652764362828"
        }
      }
    }
  ]
}

Response examples (400)

{
  "error": "no authentication methods were specified",
  "error_code": "InvalidParameter",
  "link": "string"
}

{
  "error": "must specify some form of authentication (either email+password, api-key, or jwt) in the request header or body",
  "error_code": "MissingParameter",
  "link": "string"
}

Response examples (401)

{
  "error": "invalid session: error finding user for endpoint",
  "error_code": "InvalidSession",
  "link": "string"
}