• Realm >
• Reference

Realm Administration API

MongoDB Realm provides an API for programmatically performing administrative tasks outside of the Realm UI. This includes tasks such as modifying authentication providers, creating rules, and defining functions. The admin API is not for Realm client applications: tasks like authenticating users, calling functions, and interacting with services should be done using the client SDK for production client uses.

API Authentication

Every request to the Realm Admin API must include a valid and current authorization token from the MongoDB Cloud API as a bearer token in the Authorization header. You will need a valid programmatic API key for MongoDB Atlas to get a token.

Once you have an API key pair, call the authentication endpoint:

copy

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"username": "<Public API Key>", "apiKey": "<Private API Key>"}' \
  https://realm.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login

If authentication succeeds, MongoDB Realm returns an access token as part of the JSON response document:

copy

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token represents a limited-time authorization to interact with the Admin API. To authenticate a request, include the token in a Bearer token Authorization header.

copy

Authorization: Bearer <access_token>

Project & Application IDs

Note

The terms Project ID and Group ID are interchangeable.

Realm APIs frequently require two parameters: your Atlas Project/Group ID, and your Realm Application ID.

Project ID

To find your Project ID, go to your Atlas administration console, click Settings in the left-hand navigation bar, and look under the Project ID heading.

Application ID

To find your Application ID, make a request to the Realm GET /groups/{groupId}/apps API endpoint.

This request has the following format, referencing the access_token described in API Authentication:

copy

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps

This will return a list of objects describing each Realm app in the provided group. The _id field contains the Application ID.

Example

Pagination with the Logging API

The Logging endpoint returns up to 100 log entries per page. If the query matches more than 100 entries, the result will be paginated. Such a result will contain two pieces of information that you will need to request the next page of entries for the same query: the nextEndDate and nextSkip fields.

Paginated results always contain the nextEndDate field. A paginated result will also contain the nextSkip field if the timestamp of the first entry on the next page is identical to the timestamp of the last entry on the current page.

To request the first page of up to 100 log entries, use the endpoint as usual:

copy

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs'

To request the next page of up to 100 log entries, pass the values of nextEndDate and nextSkip as the end_date and skip parameters, respectively:

copy

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs?end_date={nextEndDate of previous response}&skip={nextSkip of previous response}'

Repeat this step to get more pages until the response does not have a nextEndDate field. This signifies that you have reached the last page.

For more information, see GET /groups/{groupId}/apps/{appId}/logs.

Draft and Deploy a Group of Changes

You can deploy a group of application changes together by creating and deploying a draft. To create and deploy a set of draft changes:

1

Create a New Draft

A draft represents a group of application changes that you can deploy or discard as a single unit. To create a draft, send a POST request to the drafts endpoint:

copy

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts'

One Draft Per User

Each user can only create a single draft at a time, either through the UI or the Admin API. If you already have an existing draft, you can discard the changes associated with it by sending a DELETE request to the draft’s endpoint:

copy

curl --request DELETE \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}'

2

Make Changes to Your Application

Once you’ve created a draft, make all of the changes that you want to include in the draft. Realm adds any application changes that you make to the draft so that you can deploy them together.

3

Deploy the Draft

After you’ve made all the changes that you want to include in the deployment, deploy the draft by sending a POST request to that draft’s deployment endpoint:

copy

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  'https://realm.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment'

Resources

Base URL

copy

https://realm.mongodb.com/api/admin/v3.0

The root API resource and starting point for the Realm API.

Realm Administrator APIs

get

/auth/providers

Enumerate available Realm administration authentication providers.

Responses

200: Successfully enumerated available authentication providers.

copy

[
  {
    "_id": "string",
    "name": "string",
    "type": "string",
    "disabled": "boolean"
  }
]

Field	Type	Description
[]	array of objects	An array of authentication providers.
[]._id	string
[].name	string
[].type	string	Possible Values: mongodb-cloud local
[].disabled	boolean

post

/auth/providers/{provider}/login

Authenticate as a Realm administrator. Use GET /auth/providers to list the available authentication providers.

Path Parameters

Name	Type	Description
provider	string	The authentication provider to use. Possible Values: mongodb-cloud local

Request Body

copy

{
  "username": "string",
  "apiKey": "string"
}

Field	Type	Description
username	string
apiKey	string

Responses

200: Authentication was successful.

copy

{
  "access_token": "string",
  "refresh_token": "string",
  "user_id": "string",
  "device_id": "string"
}

Field	Type	Description
access_token	string	An access token you may provide in the Authorization header of API requests. API Authentication demonstrates how to use this token.
refresh_token	string	A refresh token you may provide in the Authorization header of POST /auth/session to obtain a new access_token for the current user session.
user_id	string	The unique _id value of the MongoDB Cloud user.
device_id	string

get

/auth/profile

Get information about the currently logged in user.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The profile was successfully retrieved.

copy

{
  "user_id": "string",
  "domain_id": "string",
  "identities": [
    {
      "_id": "string",
      "name": "string",
      "type": "string",
      "disabled": "boolean"
    }
  ],
  "data": {
    "email": "string",
    "name": "string"
  },
  "type": "string",
  "roles": [
    {
      "role_name": "string",
      "group_id": "Any"
    }
  ]
}

Field	Type	Description
user_id	string
domain_id	string
identities	array
identities.[]._id	string
identities.[].name	string
identities.[].type	string	Possible Values: mongodb-cloud local
identities.[].disabled	boolean
data	object
data.email	string
data.name	string
type	string	Possible Values: normal server system unknown
roles	array
roles.[].role_name	string
roles.[].group_id	string	An Atlas Project/Group ID.

delete

/auth/session

Delete a Realm access token.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

post

/auth/session

Obtain a Realm access token.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the refresh_token field of the POST /auth/providers/{provider}/login API endpoint.

Responses

201: Successfully created.

copy

{
  "access_token": "string"
}

Field	Type	Description
access_token	string

get

/groups/{groupID}/apps/{appID}/services/{serviceId}/commands/build_info

Get information about the underlying Atlas mongod.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

An empty object.

copy

{}

Responses

200: The build information was successfully retrieved.

copy

{
  "version": "string",
  "gitVersion": "string",
  "versionArray": [
    "integer"
  ],
  "javascriptEngine": "string",
  "bits": "string",
  "debug": "boolean",
  "maxBsonObjectSize": "integer"
}

Field	Type	Description
version	string	Human-readable version information about the mongod instance. This string will take the format <major>.<minor>.<patch>.
gitVersion	string	The commit identifier that identifies the state of the code use to build the mongod.
versionArray	array	An array that conveys version information about the mongod instance. See version for a more readable version of this string.
javascriptEngine	string	A string that reports the JavaScript engine used in the mongod instance. By default, this is mozjs after version 3.2, and previously V8.
bits	string	A number that reflects the target processor architecture of the mongod binary.
debug	boolean	A boolean that reflects whether or not the mongod instance was built with debugging options.
maxBsonObjectSize	integer	A number that reports the Maximum BSON Document Size

API Key APIs

get

/groups/{groupId}/apps/{appId}/api_keys

List API keys associated with a Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The API keys were successfully listed.

copy

[
  {
    "_id": "string",
    "name": "string",
    "disabled": "boolean"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string
[].disabled	boolean

post

/groups/{groupId}/apps/{appId}/api_keys

Create a new API key.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The API key to create.

copy

{
  "name": "string"
}

Field	Type	Description
name	string

Responses

201: The API key was successfully created.

copy

{
  "_id": "string",
  "key": "string",
  "name": "string",
  "disabled": "string"
}

Field	Type	Description
_id	string
key	string
name	string
disabled	string

get

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}

Retrieve information about an API key.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
apiKeyId	string	API Key ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The API key was successfully retrieved.

copy

{
  "_id": "string",
  "name": "string",
  "disabled": "string"
}

Field	Type	Description
_id	string
name	string
disabled	string

delete

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}

Delete an API key.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
apiKeyId	string	API Key ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The API key was successfully deleted.

put

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/enable

Enable an API key.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
apiKeyId	string	API Key ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The API key was successfully enabled.

put

/groups/{groupId}/apps/{appId}/api_keys/{apiKeyId}/disable

Disable an API key.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
apiKeyId	string	API Key ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The API key was successfully disabled.

Billing APIs

get

/groups/{groupId}/measurements

List the request, compute, sync, and data transfer usage in a given period for billing purposes.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.

Query Parameters

Name	Type	Description
start	string	The ISO 8601 date and time of the start of the query period. Default is 00:00:00 UTC on the first day of the current month.
end	string	The ISO 8601 date and time of the end of the query period. Default is 23:59:59 UTC on the the last day of the current month.
granularity	string	Specifies the granularity of the query period, either P31D (31 day) or PT1H (1 hour). Default is P31D. Possible Values: P31D PT1H

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The measurements were successfully returned.

copy

{
  "start": "string",
  "end": "string",
  "granularity": "string",
  "group_id": "string",
  "measurements": [
    {
      "name": "string",
      "units": "string",
      "data_points": [
        {
          "timestamp": "string",
          "value": "number"
        }
      ]
    }
  ]
}

Field	Type	Description
start	string	The RFC 3339 date and time of the start of the query period, which can be specified with the start query parameter.
end	string	The RFC 3339 date and time of the end of the query period, which can be specified with the end query parameter.
granularity	string	The granularity, which can be specified with the granularity query parameter.
group_id	string	The Atlas Group ID.
measurements	array	The array of measurements.
measurements.[].name	string	The usage metric represented by each data point. See billing. Possible Values: request_count compute_time data_out sync_time
measurements.[].units	string	The unit of the value of each data point. Possible Values: <empty string> HOURS GIGABYTES
measurements.[].data_points	array	The array of data points for this measurement. A finer granularity results in more data points.
measurements.[].data_points.[].timestamp	string	The ISO 8601 date and time of the data point.
measurements.[].data_points.[].value	number	The value at the time in the unit of the measurement.

400: There is an error in the request.

copy

{
  "error": "string"
}

Field	Type	Description
error	string	A message describing the error.

get

/groups/{groupId}/apps/{appId}/measurements/

List the request, compute, sync, data transfer, and memory usage of a specific app in a given period for billing purposes.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
start	string	The ISO 8601 date and time of the start of the query period. Default is 00:00:00 UTC on the first day of the current month.
end	string	The ISO 8601 date and time of the end of the query period. Default is 23:59:59 UTC on the the last day of the current month.
granularity	string	Specifies the granularity of the query period, either P31D (31 day) or PT1H (1 hour). Default is P31D. Possible Values: P31D PT1H

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The measurements were successfully returned.

copy

{
  "start": "string",
  "end": "string",
  "granularity": "string",
  "group_id": "string",
  "appId": "string",
  "appName": "string",
  "measurements": [
    {
      "name": "string",
      "units": "string",
      "data_points": [
        {
          "timestamp": "string",
          "value": "number"
        }
      ]
    }
  ]
}

Field	Type	Description
start	string	The RFC 3339 date and time of the start of the query period, which can be specified with the start query parameter.
end	string	The RFC 3339 date and time of the end of the query period, which can be specified with the end query parameter.
granularity	string	The granularity, which can be specified with the granularity query parameter.
group_id	string	The Atlas Group ID.
appId	string	The Realm app ID specified by the appId path parameter.
appName	string	The name of the Realm app specified by the appId path parameter.
measurements	array	The array of measurements.
measurements.[].name	string	The usage metric represented by each data point. See billing. Possible Values: request_count compute_time data_out sync_time mem_usage
measurements.[].units	string	The unit of the value of each data point. Possible Values: <empty string> HOURS GIGABYTES GIGABYTE_SECONDS
measurements.[].data_points	array	The array of data points for this measurement. A finer granularity results in more data points.
measurements.[].data_points.[].timestamp	string	The ISO 8601 date and time of the data point.
measurements.[].data_points.[].value	number	The value at the time in the unit of the measurement.

400: There is an error in the request.

copy

{
  "error": "string"
}

Field	Type	Description
error	string	A message describing the error.

Secrets APIs

get

/groups/{groupId}/apps/{appId}/secrets

List Secrets associated with a Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The Secrets were successfully listed.

copy

[
  {
    "_id": "string",
    "name": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string

post

/groups/{groupId}/apps/{appId}/secrets

Create a new Secret.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The Secret to create.

copy

{
  "name": "string",
  "value": "string"
}

Field	Type	Description
name	string
value	string

Responses

201: The Secret was successfully created.

copy

{
  "_id": "string",
  "name": "string"
}

Field	Type	Description
_id	string
name	string

put

/groups/{groupId}/apps/{appId}/secrets/{secretId}

Modify a Secret associated with a Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
secretId	string	Secret ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The modified value of the Secret.

copy

{
  "_id": "string",
  "name": "string",
  "value": "string"
}

Field	Type	Description
_id	string
name	string
value	string

Responses

200: The Secret was successfully modified.

copy

[
  {
    "_id": "string",
    "name": "string",
    "value": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string
[].value	string

delete

/groups/{groupId}/apps/{appId}/secrets/{secretId}

Delete a Secret associated with a Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
secretId	string	Secret ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The Secret was successfully deleted.

Application-level APIs

get

/groups/{groupId}/apps

List all Realm apps within an Atlas project/group.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "client_app_id": "string",
    "name": "string",
    "location": "string",
    "deployment_model": "string",
    "domain_id": "string",
    "group_id": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string	The application’s unique internal ID.
[].client_app_id	string	The application’s public App ID.
[].name	string	The name of the application.
[].location	string	The application’s deployment region.
[].deployment_model	string	The application’s deployment model.
[].domain_id	string
[].group_id	string	An Atlas Project/Group ID.

post

/groups/{groupId}/apps

Create a new Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.

Query Parameters

Name	Type	Description
defaults	boolean	Whether or not to create a default application.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The application to create.

copy

{
  "name": "string"
}

Field	Type	Description
name	string

Responses

201: The application was successfully created.

get

/groups/{groupId}/apps/{appId}

Retrieve an application definition.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The application was successfully retrieved.

copy

{
  "_id": "string",
  "client_app_id": "string",
  "name": "string",
  "location": "string",
  "deployment_model": "string",
  "domain_id": "string",
  "group_id": "string"
}

Field	Type	Description
_id	string	The application’s unique internal ID.
client_app_id	string	The application’s public App ID.
name	string	The name of the application.
location	string	The application’s deployment region.
deployment_model	string	The application’s deployment model.
domain_id	string
group_id	string	An Atlas Project/Group ID.

delete

/groups/{groupId}/apps/{appId}

Delete an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The application was successfully deleted.

get

/groups/{groupId}/apps/{appId}/export

Export an application as a zip file.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The application was successfully exported.

Auth Provider APIs

get

/groups/{groupId}/apps/{appId}/auth_providers

List authentication providers within a Realm app.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "name": "string",
    "type": "string",
    "disabled": "boolean"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string
[].type	string	Possible Values: mongodb-cloud local
[].disabled	boolean

post

/groups/{groupId}/apps/{appId}/auth_providers

Create an authentication provider.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

copy

{
  "name": "string",
  "type": "string",
  "disabled": "boolean",
  "config": "object"
}

Field	Type	Description
name	string
type	string	Possible Values: mongodb-cloud local
disabled	boolean
config	object

Responses

201: Successfully created.

get

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Retrieve information about one of an application’s authentication providers

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
providerId	string	Provider ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "disabled": "boolean",
  "config": "object"
}

Field	Type	Description
_id	string
name	string
type	string	Possible Values: mongodb-cloud local
disabled	boolean
config	object

delete

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Delete an authentication provider.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
providerId	string	Provider ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

patch

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}

Update an authentication provider.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
providerId	string	Provider ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "disabled": "boolean",
  "config": "object"
}

Field	Type	Description
_id	string
name	string
type	string	Possible Values: mongodb-cloud local
disabled	boolean
config	object

Responses

204: Successfully updated.

put

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/disable

Disable an authentication provider.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
providerId	string	Provider ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully disabled.

put

/groups/{groupId}/apps/{appId}/auth_providers/{providerId}/enable

Enable an authentication provider.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
providerId	string	Provider ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully enabled.

Email APIs

post

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/send_confirm

Send a confirmation email.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
email	string	Email address

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully sent.

post

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/confirm

Confirm a pending user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
email	string	Email address

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully confirmed.

post

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}/run_confirm

Re-runs a pending user’s confirmation workflow.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
email	string	Email address

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

202: Successfully re-ran confirmation workflow.

400: User is already confirmed or Email/Password authentication is not enabled.

404: User does not exist.

Functions APIs

post

/groups/{groupId}/apps/{appId}/debug/execute_function

Execute a function for testing.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

201: Successfully executed.

post

/groups/{groupId}/apps/{appId}/debug/execute_function_source

Execute a function’s source code for testing.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
user_id	string	The user as which to execute the function.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The source to execute.

copy

{
  "eval_source": "string",
  "source": "string"
}

Field	Type	Description
eval_source	string
source	string

Responses

200: Successfully executed.

copy

{
  "error": "object",
  "logs": "Any",
  "result": "object",
  "stats": "Any"
}

Field	Type	Description
error	object
logs	any
result	object
stats	object

get

/groups/{groupId}/apps/{appId}/functions

List functions.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "name": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string

post

/groups/{groupId}/apps/{appId}/functions

Create a new function.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The function to create

copy

{
  "can_evaluate": "object",
  "name": "string",
  "private": "boolean",
  "source": "string"
}

Field	Type	Description
can_evaluate	object	A JSON expression that evaluates to true if the Function is allowed to run in response to an incoming request.
name	string	A unique name for the Function.
private	boolean	If true, the function is hidden from client applications. You can still call a private function from JSON expressions and other functions, including incoming webhooks and triggers.
source	string	The stringified source code for the function. The code must be valid ES6.

Responses

201: The function was successfully created.

copy

{
  "can_evaluate": "object",
  "name": "string",
  "private": "boolean",
  "source": "string"
}

Field	Type	Description
can_evaluate	object	A JSON expression that evaluates to true if the Function is allowed to run in response to an incoming request.
name	string	A unique name for the Function.
private	boolean	If true, the function is hidden from client applications. You can still call a private function from JSON expressions and other functions, including incoming webhooks and triggers.
source	string	The stringified source code for the function. The code must be valid ES6.

get

/groups/{groupId}/apps/{appId}/functions/{functionId}

Retrieve a function.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
functionId	string	Function ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The function was successfully retrieved.

copy

{
  "_id": "string",
  "can_evaluate": "object",
  "name": "string",
  "private": "boolean",
  "source": "string"
}

Field	Type	Description
_id	string
can_evaluate	object	A JSON expression that evaluates to true if the Function is allowed to run in response to an incoming request.
name	string	A unique name for the Function.
private	boolean	If true, the function is hidden from client applications. You can still call a private function from JSON expressions and other functions, including incoming webhooks and triggers.
source	string	The stringified source code for the function. The code must be valid ES6.

delete

/groups/{groupId}/apps/{appId}/functions/{functionId}

Delete a function.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
functionId	string	Function ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The function was successfully deleted.

put

/groups/{groupId}/apps/{appId}/functions/{functionId}

Update a function.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
functionId	string	Function ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The function was successfully updated.

copy

{
  "can_evaluate": "object",
  "name": "string",
  "private": "boolean",
  "source": "string"
}

Field	Type	Description
can_evaluate	object	A JSON expression that evaluates to true if the Function is allowed to run in response to an incoming request.
name	string	A unique name for the Function.
private	boolean	If true, the function is hidden from client applications. You can still call a private function from JSON expressions and other functions, including incoming webhooks and triggers.
source	string	The stringified source code for the function. The code must be valid ES6.

Logging APIs

get

/groups/{groupId}/apps/{appId}/logs

Retrieve MongoDB Realm logs.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
co_id	string	Return only log messages associated with the given request ID.
errors_only	boolean	Whether to only return errors.
user_id	string	Return only log messages associated with the given user_id.
start_date	string	The date and time in ISO 8601 at which to begin returning results, exclusive.
end_date	string	The date and time in ISO 8601 at which to cease returning results, inclusive.
skip	integer	The offset number of matching log entries to skip before including them in the response.
limit	integer	The maximum number of log entries to include in the response. If the query matches more than this many logs, it returns documents in ascending order by date until the limit is reached.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "logs": [
    {
      "_id": "string",
      "co_id": "string",
      "domain_id": "string",
      "app_id": "string",
      "group_id": "string",
      "request_url": "string",
      "request_method": "string",
      "started": "string",
      "completed": "string",
      "error": "string",
      "error_code": "string",
      "status": "integer"
    }
  ],
  "nextEndDate": "string",
  "nextSkip": "integer"
}

Field	Type	Description
logs	array
logs.[]._id	string
logs.[].co_id	string
logs.[].domain_id	string
logs.[].app_id	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
logs.[].group_id	string	An Atlas Project/Group ID.
logs.[].request_url	string
logs.[].request_method	string
logs.[].started	string
logs.[].completed	string
logs.[].error	string
logs.[].error_code	string
logs.[].status	integer
nextEndDate	string	The end date and time of the next page of log entries in ISO 8601 format. MongoDB Realm paginates the result sets of queries that match more than 100 log entries and includes this field in paginated responses. To get the next page of up to 100 entries, pass this value as the end_date parameter in a subsequent request.
nextSkip	integer	The offset into the next page of log entries in ISO 8601 format. MongoDB Realm paginates the result sets of queries that match more than 100 log entries and includes this field in paginated responses where the first entry on the next page has the same timestamp as the last entry on this page. To get the next page of up to 100 entries, pass this value, if it is present, as the skip parameter in a subsequent request.

Notifications APIs

get

/groups/{groupId}/apps/{appId}/push/notifications

List push notifications.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
state	string	Only list notifications with the given state. Possible Values: sent draft

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "appID": "string",
    "label": "string",
    "message": "string",
    "topic": "string",
    "created": "string",
    "sent": "string",
    "state": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].appID	string
[].label	string
[].message	string
[].topic	string
[].created	string
[].sent	string
[].state	string	Possible Values: sent draft

post

/groups/{groupId}/apps/{appId}/push/notifications

Create a push notification.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The notification to create.

copy

{
  "label": "string",
  "message": "string",
  "topic": "string",
  "state": "string"
}

Field	Type	Description
label	string
message	string
topic	string
state	string	Possible Values: sent draft

Responses

201: Successfully created.

get

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Retrieve a push notification message.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
messageId	string	Message ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "_id": "string",
  "appID": "string",
  "label": "string",
  "message": "string",
  "topic": "string",
  "created": "string",
  "sent": "string",
  "state": "string"
}

Field	Type	Description
_id	string
appID	string
label	string
message	string
topic	string
created	string
sent	string
state	string	Possible Values: sent draft

delete

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Delete a push notification message.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
messageId	string	Message ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

put

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}

Update a push notification message.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
messageId	string	Message ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully updated.

copy

{
  "_id": "string",
  "appID": "string",
  "label": "string",
  "message": "string",
  "topic": "string",
  "created": "string",
  "sent": "string",
  "state": "string"
}

Field	Type	Description
_id	string
appID	string
label	string
message	string
topic	string
created	string
sent	string
state	string	Possible Values: sent draft

put

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/type

Set a push notification’s type.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
messageId	string	Message ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully set.

post

/groups/{groupId}/apps/{appId}/push/notifications/{messageId}/send

Send a push notification.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
messageId	string	Message ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully sent.

Rules APIs

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

List rules.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "name": "string",
    "actions": "Any",
    "when": "object"
  }
]

Field	Type	Description
[]	array of objects
[].name	string
[].actions	array
[].when	object

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

Create a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The rule to create.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

Responses

201: Successfully created.

copy

{
  "_id": "string",
  "name": "string"
}

Field	Type	Description
_id	string
name	string

409: There is already a rule with the given name.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Retrieve a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

delete

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Delete a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

put

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Update a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The new state of the rule.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

Responses

200: Successfully updated.

Security APIs

get

/groups/{groupId}/apps/{appId}/security/allowed_request_origins

List the allowed HTTP origins from which MongoDB Realm should allow requests.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  "string"
]

Field	Type	Description
[]	array of strings

post

/groups/{groupId}/apps/{appId}/security/allowed_request_origins

Set the allowed HTTP origins from which MongoDB Realm should allow requests.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

A list of HTTP origins.

copy

[
  "string"
]

Field	Type	Description
[]	array of strings

Responses

204: The allowed HTTP origins were successfully set.

Services APIs

get

/groups/{groupId}/apps/{appId}/services

List all services within an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed services.

copy

[
  {
    "_id": "string",
    "name": "string",
    "type": "string",
    "version": "integer"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string
[].type	string
[].version	integer

post

/groups/{groupId}/apps/{appId}/services

Create a service.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

201: Successfully created the service.

copy

{
  "name": "string",
  "type": "string",
  "config": "object"
}

Field	Type	Description
name	string
type	string
config	object

409: There is already a service with the given name.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}

Retrieve a service.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The service was successfully deleted.

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "version": "integer"
}

Field	Type	Description
_id	string
name	string
type	string
version	integer

delete

/groups/{groupId}/apps/{appId}/services/{serviceId}

Delete a service.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The service was successfully deleted.

patch

/groups/{groupId}/apps/{appId}/services/{serviceId}

Update a service.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully updated.

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/{commandName}

Run a command associated with a service.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
commandName	string	Command name

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully executed.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/config

Retrieve a service’s configuration.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

patch

/groups/{groupId}/apps/{appId}/services/{serviceId}/config

Update a service’s configuration.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully updated.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

List rules.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "name": "string",
    "actions": "Any",
    "when": "object"
  }
]

Field	Type	Description
[]	array of objects
[].name	string
[].actions	array
[].when	object

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules

Create a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The rule to create.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

Responses

201: Successfully created.

copy

{
  "_id": "string",
  "name": "string"
}

Field	Type	Description
_id	string
name	string

409: There is already a rule with the given name.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Retrieve a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

delete

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Delete a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

put

/groups/{groupId}/apps/{appId}/services/{serviceId}/rules/{ruleId}

Update a rule.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
ruleId	string	Rule ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The new state of the rule.

copy

{
  "name": "string",
  "actions": "Any",
  "when": "object"
}

Field	Type	Description
name	string
actions	array
when	object

Responses

200: Successfully updated.

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/commands/generate_schema

Sample a subset of documents in a collection to generate a JSON schema.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

copy

{
  "database_name": "string",
  "collection_name": "string",
  "limit": "integer"
}

Field	Type	Description
database_name	string	The name of the database that contains the collection.
collection_name	string	The name of the collection to sample and generate a schema for.
limit	integer	The maximum number of documents to include in the sample.

Responses

200: Successfully generated schema

copy

{
  "schema": "object"
}

Field	Type	Description
schema	object	The generated JSON schema

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

List webhooks.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed incoming webhooks.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

Create a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The webhook to create.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

Responses

201: Successfully created.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Retrieve a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

delete

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Delete a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

put

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Update a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The updated state of the webhook.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

Responses

200: Successfully updated.

Sync APIs

get

/groups/{groupId}/apps/{appId}/sync/data

Get sync information for a specific linked MongoDB cluster.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
service_id	string	The Service ID for the linked cluster.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "service_id": "string",
  "partition_fields": [
    {
      "key": "string",
      "type": "string"
    }
  ]
}

Field	Type	Description
service_id	string	The Service ID for the currently synced cluster, if there is one.
partition_fields	array	A list of valid partition keys based on the cluster’s collection schemas.
partition_fields.[].key	string
partition_fields.[].type	string

Users APIs

get

/groups/{groupId}/apps/{appId}/users

List users.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "identities": "Any",
    "type": "string",
    "creation_date": "integer",
    "last_authentication_date": "integer",
    "disabled": "boolean",
    "data": "object"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].identities	array
[].type	string
[].creation_date	integer
[].last_authentication_date	integer
[].disabled	boolean
[].data	object

post

/groups/{groupId}/apps/{appId}/users

Create a user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The user to create

copy

{
  "email": "string",
  "password": "string"
}

Field	Type	Description
email	string
password	string

Responses

201: Successfully created.

copy

{
  "_id": "string",
  "identities": "Any",
  "type": "string",
  "creation_date": "integer",
  "last_authentication_date": "integer",
  "disabled": "boolean",
  "data": "object"
}

Field	Type	Description
_id	string
identities	array
type	string
creation_date	integer
last_authentication_date	integer
disabled	boolean
data	object

get

/groups/{groupId}/apps/{appId}/users/{uid}

Retrieve a user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

copy

{
  "_id": "string",
  "identities": "Any",
  "type": "string",
  "creation_date": "integer",
  "last_authentication_date": "integer",
  "disabled": "boolean",
  "data": "object"
}

Field	Type	Description
_id	string
identities	array
type	string
creation_date	integer
last_authentication_date	integer
disabled	boolean
data	object

delete

/groups/{groupId}/apps/{appId}/users/{uid}

Delete a user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

get

/groups/{groupId}/apps/{appId}/users/{uid}/devices

List a user’s devices.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  "object"
]

Field	Type	Description
[]	array of objects

put

/groups/{groupId}/apps/{appId}/users/{uid}/logout

Revoke all of a user’s sessions.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully revoked.

put

/groups/{groupId}/apps/{appId}/users/{uid}/enable

Enable a user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully enabled.

put

/groups/{groupId}/apps/{appId}/users/{uid}/disable

Disable a user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
uid	string	UID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully disabled.

delete

/groups/{groupId}/apps/{appId}/user_registrations/by_email/{email}

Delete a pending user.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
email	string	Email address

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

Values APIs

get

/groups/{groupId}/apps/{appId}/values

List all values defined in an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: values were successfully enumerated.

copy

[
  {
    "_id": "string",
    "name": "string",
    "private": "boolean"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string
[].name	string
[].private	boolean

post

/groups/{groupId}/apps/{appId}/values

Define a Value in an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The value to create.

copy

{
  "name": "string",
  "private": "boolean",
  "value": "Any"
}

Field	Type	Description
name	string
private	boolean
value	any

Responses

201: The value was successfully defined.

copy

{
  "name": "string",
  "private": "boolean",
  "value": "Any"
}

Field	Type	Description
name	string
private	boolean
value	any

get

/groups/{groupId}/apps/{appId}/values/{valueId}

Retrieve a value definition from an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
valueId	string	Value ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved the value.

copy

{
  "_id": "string",
  "name": "string",
  "private": "boolean",
  "value": "Any"
}

Field	Type	Description
_id	string
name	string
private	boolean
value	any

delete

/groups/{groupId}/apps/{appId}/values/{valueId}

Delete a value defined in an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
valueId	string	Value ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted the value.

put

/groups/{groupId}/apps/{appId}/values/{valueId}

Update a value definition in an application.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
valueId	string	Value ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully updated the value.

copy

[
  {
    "name": "string",
    "private": "boolean",
    "value": "Any"
  }
]

Field	Type	Description
[]	array of objects
[].name	string
[].private	boolean
[].value	any

Incoming Webhook APIs

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

List webhooks.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed incoming webhooks.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

post

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks

Create a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The webhook to create.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

Responses

201: Successfully created.

get

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Retrieve a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved.

delete

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Delete a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully deleted.

put

/groups/{groupId}/apps/{appId}/services/{serviceId}/incoming_webhooks/{incomingWebhookId}

Update a webhook.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
serviceId	string	Service ID
incomingWebhookId	string	Incoming webhook ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The updated state of the webhook.

copy

{
  "name": "string",
  "function_source": "string",
  "respond_result": "boolean",
  "options": {
    "secret": "string",
    "secretAsQueryParam": "boolean"
  }
}

Field	Type	Description
name	string
function_source	string
respond_result	boolean
options	object
options.secret	string
options.secretAsQueryParam	boolean

Responses

200: Successfully updated.

Event Trigger APIs

post

/groups/{groupId}/apps/{appId}/triggers

Create a trigger.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The trigger to create.

copy

{
  "name": "string",
  "type": "string",
  "function_id": "string",
  "disabled": "boolean",
  "config": {
    "operation_types": "array of strings",
    "operation_type": "string",
    "providers": "string",
    "database": "string",
    "collection": "string",
    "service_id": "string",
    "match": "object",
    "full_document": "boolean",
    "schedule": "string"
  },
  "event_processors": "object"
}

Field	Type	Description
name	string	The name of the trigger.
type	string	The type of the trigger. Possible Values: DATABASE AUTHENTICATION
function_id	string	The ID of the function associated with the trigger.
disabled	boolean	Default: false If true, the trigger is disabled.
config	object	An object that defines configuration values for the trigger.
config.operation_types	array of strings	Required for Database Triggers Minimum Items: 1 The database event operation types to listen for. Valid values: INSERT UPDATE REPLACE DELETE
config.operation_type	string	Required for Authentication Triggers The authentication operation type to listen for. Valid values: LOGIN CREATE DELETE
config.providers	string	Only Available for Authentication Triggers A list of one or more authentication provider id values. The trigger will only listen for authentication events produced by these providers.
config.database	string	Required for Database Triggers The name of the MongoDB database that contains the watched collection.
config.collection	string	Required for Database Triggers The name of the MongoDB collection that the trigger watches for change events. The collection must be part of the specified database.
config.service_id	string	Required for Database Triggers The ID of the MongoDB Service associated with the trigger.
config.match	object	Only Available for Database Triggers A $match expression document that MongoDB Realm includes in the underlying change stream pipeline for the trigger. This is useful when you want to filter change events beyond their operation type. The trigger will only fire if the expression evaluates to true for a given change event.
config.full_document	boolean	Only Available for Database Triggers If true, indicates that UPDATE change events should include the most current majority-committed version of the modified document in the fullDocument field.
config.schedule	string	Only Available for Scheduled Triggers A cron expression that defines the trigger schedule.
event_processors	object	An object where each field name is an event processor ID and each value is an object that configures its corresponding event processor. The following event processors are supported: AWS_EVENTBRIDGE

Responses

201: Successfully created.

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "function_id": "string",
  "function_name": "string",
  "disabled": "boolean"
}

Field	Type	Description
_id	string	The unique ID of the trigger.
name	string	The name of the trigger.
type	string	The type of the trigger.
function_id	string	The ID of the function associated with the trigger.
function_name	string	The name of the function associated with the trigger.
disabled	boolean	If true, the trigger is disabled and will not fire.

get

/groups/{groupId}/apps/{appId}/triggers

List all triggers.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed triggers.

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "function_id": "string",
  "function_name": "string",
  "disabled": "boolean"
}

Field	Type	Description
_id	string	The unique ID of the trigger.
name	string	The name of the trigger.
type	string	The type of the trigger.
function_id	string	The ID of the function associated with the trigger.
function_name	string	The name of the function associated with the trigger.
disabled	boolean	If true, the trigger is disabled and will not fire.

put

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Update a trigger.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
triggerId	string	The ObjectID of the trigger.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The trigger to update.

copy

{
  "name": "string",
  "type": "string",
  "function_id": "string",
  "disabled": "boolean",
  "config": {
    "operation_types": "array of strings",
    "operation_type": "string",
    "providers": "string",
    "database": "string",
    "collection": "string",
    "service_id": "string",
    "match": "object",
    "full_document": "boolean",
    "schedule": "string"
  },
  "event_processors": "object"
}

Field	Type	Description
name	string	The name of the trigger.
type	string	The type of the trigger. Possible Values: DATABASE AUTHENTICATION
function_id	string	The ID of the function associated with the trigger.
disabled	boolean	Default: false If true, the trigger is disabled.
config	object	An object that defines configuration values for the trigger.
config.operation_types	array of strings	Required for Database Triggers Minimum Items: 1 The database event operation types to listen for. Valid values: INSERT UPDATE REPLACE DELETE
config.operation_type	string	Required for Authentication Triggers The authentication operation type to listen for. Valid values: LOGIN CREATE DELETE
config.providers	string	Only Available for Authentication Triggers A list of one or more authentication provider id values. The trigger will only listen for authentication events produced by these providers.
config.database	string	Required for Database Triggers The name of the MongoDB database that contains the watched collection.
config.collection	string	Required for Database Triggers The name of the MongoDB collection that the trigger watches for change events. The collection must be part of the specified database.
config.service_id	string	Required for Database Triggers The ID of the MongoDB Service associated with the trigger.
config.match	object	Only Available for Database Triggers A $match expression document that MongoDB Realm includes in the underlying change stream pipeline for the trigger. This is useful when you want to filter change events beyond their operation type. The trigger will only fire if the expression evaluates to true for a given change event.
config.full_document	boolean	Only Available for Database Triggers If true, indicates that UPDATE change events should include the most current majority-committed version of the modified document in the fullDocument field.
config.schedule	string	Only Available for Scheduled Triggers A cron expression that defines the trigger schedule.
event_processors	object	An object where each field name is an event processor ID and each value is an object that configures its corresponding event processor. The following event processors are supported: AWS_EVENTBRIDGE

Responses

204: Successfully updated the trigger.

409: Encountered an error while updating the trigger.

copy

{
  "error": "string",
  "error_code": "string"
}

Field	Type	Description
error	string	A message that describes the error.
error_code	string	The error type.

get

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Retrieve the configuration for a specific trigger.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
triggerId	string	The ObjectID of the trigger.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved trigger.

copy

{
  "_id": "string",
  "name": "string",
  "type": "string",
  "function_id": "string",
  "function_name": "string",
  "disabled": "boolean"
}

Field	Type	Description
_id	string	The unique ID of the trigger.
name	string	The name of the trigger.
type	string	The type of the trigger.
function_id	string	The ID of the function associated with the trigger.
function_name	string	The name of the function associated with the trigger.
disabled	boolean	If true, the trigger is disabled and will not fire.

delete

/groups/{groupId}/apps/{appId}/triggers/{triggerId}

Delete a trigger.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
triggerId	string	The ObjectID of the trigger.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully deleted the trigger.

copy

{}

put

/groups/{groupId}/apps/{appId}/triggers/{triggerId}/resume

Resume a suspended trigger.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
triggerId	string	The ObjectID of the trigger.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: Successfully resumed the trigger.

404: Trigger not found.

copy

{
  "error": "string"
}

Field	Type	Description
error	string	A description of the error that Realm encountered.

Static File Hosting APIs

get

/groups/{groupId}/apps/{appId}/hosting/assets

List all hosted assets.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed hosted files.

copy

[
  {
    "appId": "string",
    "last_modified": "integer",
    "url": "string",
    "path": "string",
    "size": "integer",
    "attrs": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "hash": "string"
  }
]

Field	Type	Description
[]	array of objects
[].appId	string	The unique App ID of the Realm app that is hosting the file.
[].last_modified	integer	The time at which the hosted asset was last modified in Unix time (number of seconds since January 1, 1970 at 00:00 UTC).
[].url	string	The full URL of the hosted asset.
[].path	string	The resource path of the hosted asset
[].size	integer	The size of the hosted asset in bytes
[].attrs	array	An array of documents that each describe a metadata attribute that applies to the asset.
[].attrs.[].name	string	The metadata attribute name.
[].attrs.[].value	string	The metadata attribute value.
[].hash	string	The MD5 checksum hash for the hosted asset

post

/groups/{groupId}/apps/{appId}/hosting/assets

Move or copy a hosted asset to a new resource path.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The hosted asset file and its metadata. (Must use Content-Type: multipart/mixed)

copy

{
  "move_from": "string",
  "move_to": "string",
  "copy_from": "string",
  "copy_to": "string"
}

Field	Type	Description
move_from	string	The current resource path of the asset to move. Must be used with move_to.
move_to	string	The resource path to which the asset will move. Must be used with move_from.
copy_from	string	The current resource path of the asset to copy. Must be used with copy_to.
copy_to	string	The resource path to which the asset will be copied. Must be used with copy_from.

Responses

204: Successfully moved/copied the hosted asset.

get

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Retrieve metadata for a specific hosted asset

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
path	string	The resource path of a hosted asset.
prefix	string	Return only those assets where the resource path begins with the specified prefix.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully retrieved metadata for the hosted file.

copy

{
  "appId": "string",
  "last_modified": "integer",
  "url": "string",
  "path": "string",
  "size": "integer",
  "attrs": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "hash": "string"
}

Field	Type	Description
appId	string	The unique App ID of the Realm app that is hosting the file.
last_modified	integer	The time at which the hosted asset was last modified in Unix time (number of seconds since January 1, 1970 at 00:00 UTC).
url	string	The full URL of the hosted asset.
path	string	The resource path of the hosted asset
size	integer	The size of the hosted asset in bytes
attrs	array	An array of documents that each describe a metadata attribute that applies to the asset.
attrs.[].name	string	The metadata attribute name.
attrs.[].value	string	The metadata attribute value.
hash	string	The MD5 checksum hash for the hosted asset

404: Asset not found.

copy

{
  "error": "string"
}

Field	Type	Description
error	string

put

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Upload or replace an asset at a specific resource path.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
path	string	The resource path of a hosted asset.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The hosted asset file and its metadata. (Must use Content-Type: multipart/mixed)

copy

{
  "meta": "object",
  "file": "string"
}

Field	Type	Description
meta	object	An asset metadata document (encoded as JSON). copy { "path": "<Asset Resource Path>", "hash": "<Asset MD5 Checksum Hash>", "size": <File size in bytes>, "attrs": [ { "name": "<Metadata Attribute Name>", "value": "<Metadata Attribute Value>", } ] }
file	string	The asset file to upload (encoded as binary).

Responses

204: Successfully added/replaced the hosted asset.

400: Bad Request.

copy

{
  "error": {
    "error": "string",
    "error_code": "string"
  }
}

Field	Type	Description
error	object
error.error	string	A message that describes the error.
error.error_code	string	The error type.

patch

/groups/{groupId}/apps/{appId}/hosting/assets/asset

Update the metadata attributes of a hosted asset at a specific resource path.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Query Parameters

Name	Type	Description
path	string	The resource path of a hosted asset.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Request Body

The new metadata attributes for the hosted asset. These attributes replace all existing attributes for the file.

copy

{
  "attributes": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

Field	Type	Description
attributes	array
attributes.[].name	string	The metadata attribute name.
attributes.[].value	string	The metadata attribute value.

Responses

204: Successfully updated the hosted asset.

400: Bad Request.

Application Deployment APIs

get

/groups/{groupId}/apps/{appId}/deployments

Return the 100 most recent application deployments.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

[
  {
    "_id": "string",
    "app_id": "string",
    "draft_id": "string",
    "user_id": "string",
    "deployed_at": "integer",
    "origin": "string",
    "commit": "string",
    "status": "string",
    "status_error_message": "string",
    "diff_url": "string"
  }
]

Field	Type	Description
[]	array of objects
[]._id	string	The unique ID of the deployment.
[].app_id	string	The unique _id value of the Realm app.
[].draft_id	string	The unique _id value of the deployment draft associated with the deployment, if applicable.
[].user_id	string	The unique _id value of the MongoDB Cloud user that deployed the draft.
[].deployed_at	integer	The time at which the deployment was made. Represented as the number of seconds since January 1, 1970.
[].origin	string	The deployment method used to create the deployment.
[].commit	string	The commit hash of the deployment (Automatic GitHub Deployment)
[].status	string	A message that indicates whether or not the deployment was successful.
[].status_error_message	string	The error message of the error that caused the deployment to fail, if applicable.
[].diff_url	string	A link to the diff of changes in the deployment (Automatic GitHub Deployment)

get

/groups/{groupId}/apps/{appId}/drafts

Return the current application deployment draft, if applicable.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully listed.

copy

{
  "_id": "string",
  "user_id": "string",
  "app": {
    "_id": "string",
    "client_app_id": "string",
    "name": "string",
    "location": "string",
    "deployment_model": "string",
    "domain_id": "string",
    "group_id": "string"
  }
}

Field	Type	Description
_id	string	The unique ID of the draft.
user_id	string	The unique _id value of the MongoDB Cloud user that created the draft.
app	object
app._id	string	The application’s unique internal ID.
app.client_app_id	string	The application’s public App ID.
app.name	string	The name of the application.
app.location	string	The application’s deployment region.
app.deployment_model	string	The application’s deployment model.
app.domain_id	string
app.group_id	string	An Atlas Project/Group ID.

post

/groups/{groupId}/apps/{appId}/drafts

Create a new application deployment draft, if none exists.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully created draft.

copy

{
  "_id": "string",
  "user_id": "string",
  "app": {
    "_id": "string",
    "client_app_id": "string",
    "name": "string",
    "location": "string",
    "deployment_model": "string",
    "domain_id": "string",
    "group_id": "string"
  }
}

Field	Type	Description
_id	string	The unique ID of the draft.
user_id	string	The unique _id value of the MongoDB Cloud user that created the draft.
app	object
app._id	string	The application’s unique internal ID.
app.client_app_id	string	The application’s public App ID.
app.name	string	The name of the application.
app.location	string	The application’s deployment region.
app.deployment_model	string	The application’s deployment model.
app.domain_id	string
app.group_id	string	An Atlas Project/Group ID.

409: Draft already exists

copy

{
  "error": "string",
  "error_code": "string"
}

Field	Type	Description
error	string	A message that describes the error.
error_code	string	The error type.

delete

/groups/{groupId}/apps/{appId}/drafts/{draftId}

Discard the specified application deployment draft.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
draftId	string	Draft ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

204: The draft was successfully discarded.

post

/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment

Deploy the specified application deployment draft.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
draftId	string	Draft ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

201: The draft was successfully deployed.

copy

{
  "_id": "string",
  "client_app_id": "string",
  "name": "string",
  "location": "string",
  "deployment_model": "string",
  "domain_id": "string",
  "group_id": "string"
}

Field	Type	Description
_id	string	The application’s unique internal ID.
client_app_id	string	The application’s public App ID.
name	string	The name of the application.
location	string	The application’s deployment region.
deployment_model	string	The application’s deployment model.
domain_id	string
group_id	string	An Atlas Project/Group ID.

get

/groups/{groupId}/apps/{appId}/drafts/{draftId}/diff

Return a diff between the currently deployed application and the specified draft.

Path Parameters

Name	Type	Description
groupId	string	An Atlas Project/Group ID.
appId	string	The ObjectID of your application. Project & Application IDs demonstrates how to find this value.
draftId	string	Draft ID

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: Successfully diffed draft.

copy

{
  "diffs": [
    "string"
  ],
  "hosting_files_diff": {
    "added": [
      "string"
    ],
    "deleted": [
      "string"
    ],
    "modified": [
      "string"
    ]
  }
}

Field	Type	Description
diffs	array	A list where each item is the line-by-line diff for a specific configuration file.
hosting_files_diff	object	The filenames of hosted files that have been added, removed, or modified.
hosting_files_diff.added	array
hosting_files_diff.deleted	array
hosting_files_diff.modified	array

Dependency APIs

get

/dependencies

List external dependencies uploaded to the Realm app.

Header Parameters

Name	Type	Description
Authorization	string	The authorization token provided in the access_token field of the POST /auth/providers/{provider}/login and POST /auth/session API endpoints.

Responses

200: The function was successfully retrieved.

copy

{
  "_id": "string",
  "location": "string",
  "user_id": "string",
  "last_modified": "integer",
  "dependencies_list": [
    {
      "name": "string",
      "version": "string"
    }
  ]
}

Field	Type	Description
_id	string	The dependency collection’s unique internal ID.
location	string	The application’s deployment region.
user_id	string	The unique _id value of the MongoDB Cloud user that uploaded the dependency collection.
last_modified	integer	The time at which the dependencies were uploaded in Unix time (number of seconds since January 1, 1970 at 00:00 UTC).
dependencies_list	array	An array of documents that each describe a dependency uploaded to the application.
dependencies_list.[].name	string	The name of the uploaded dependency.
dependencies_list.[].version	string	The version of the uploaded dependency.

←   Realm Application Security Realm CLI Authenticate With API Token  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.