Find One Document

POST /action/findOne

Access token Email & Password Api key Custom jwt

Find a single document that matches 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.

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.

Responses

200

application/json

application/json application/ejson

Found
Hide response attribute Show response attribute object
- document object | null
  
  A document that matches the specified filter. If no documents match, this is null.
Hide response attribute Show response attribute object
- document object | null
  
  A document that matches the specified filter. If no documents match, this is null.
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/findOne

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/findOne" \
  -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": {
      "text": "Do the dishes"
    }
  }'

Request example

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

Request example

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

Response examples (200)

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

Response examples (200)

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

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