MongoDB Atlas App Services Admin API (3.0)

Download OpenAPI specification:Download

The App Services Admin API lets you programmatically perform administrative tasks over HTTPS. This includes defining & configuring things like:

  • App Deployment & Security
  • APIs & Endpoints
  • Authentication & User Management
  • Data Sources
  • Device Sync
  • Environments
  • Functions
  • Logs
  • Rules
  • Schemas
  • Static Hosting
  • Triggers
  • Usage & Billing Metrics
  • Values & Secrets

The Admin API is for application development, configuration, and deployment. To actually use the features you configure with the Admin API, client applications connect with an Atlas Device SDK or over an HTTPS API specific to your App.

Project & Application IDs

Note: The terms Project ID and Group ID are interchangeable.

Atlas App Services Admin API endpoints frequently require you to include two parameters in the URL:

  • Your Atlas Project ID (also sometimes called a Group ID)
  • Your App Services Application ID

Project ID

You can find your Project ID from the MongoDB Atlas dashboard or with the MongoDB Atlas CLI.

Application ID

To find an Application ID, make a request to the List Apps endpoint for your project. You'll need an access_token to make this request. To learn how to get one, see Get an Admin API Session Access Token.

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

This will return a list of objects describing each App Services App in the provided project/group. For Admin API requests, your Application ID is the ObjectId value in the _id field, not the client_app_id.

[
  {
    "_id": "5997529e46224c6e42gb6dd9",
    "group_id": "57879f6cc4b32dbe440bb8c5",
    "domain_id": "5886619e46124e4c42fb5dd8",
    "client_app_id": "myapp-abcde",
    "name": "myapp",
    "location": "US-VA",
    "deployment_model": "GLOBAL",
    "last_used": 1615153544,
    "last_modified": 0,
    "product": "standard",
    "environment": ""
  }
]

Get an Admin API Session Access Token

Every request to the App Services Admin API must include a valid, unexpired access token issued by the MongoDB Cloud API. You include this token in the Authorization header of each request using the bearer auth scheme.

You need a valid MongoDB Atlas programmatic API key for MongoDB Atlas to get a token.

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

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

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

{
  "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.

Authorization: Bearer <access_token>

Refresh an Admin API Session Access Token

Session access tokens expire 30 minutes after they are issued. When you login, the response also includes a refresh_token that you can use to get a new access token. This is useful because you only need to log in with credentials one time. After that you can use the refresh token to re-authenticate for as long as its valid.

By default, refresh tokens expire 60 days after being issued. You can customize refresh token expiration for a minimum of 30 minutes or a maximum of 5 years.

To refresh your authentication and get a new access_token, call the auth session endpoint with your refresh_token in the Authorization header:

curl --request POST \
  --header 'Authorization: Bearer <refresh_token>' \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/session

If the refresh token is valid, the response body includes a new access_token that's valid for the next 30 minutes:

{
  "access_token": "<access_token>"
}

Administrator

Log in and adminstrate App Services Apps.

List App Services Admin Auth Providers

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Authenticate as an App Services administrator

Authenticate as an App Services administrator using an Atlas programmatic API key pair. To learn more, see Get An Admin API Session Access Token.

Request Body schema: application/json
username
required
string
apiKey
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "apiKey": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "user_id": "string",
  • "device_id": "string"
}

Get information about the currently logged in user

Authorizations:
tokenAuth

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "domain_id": "string",
  • "identities": [
    ],
  • "data": {
    },
  • "type": "normal",
  • "roles": [
    ]
}

Obtain a session access token

Authorizations:
refreshAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "string"
}

Delete a session access token

Authorizations:
tokenAuth

Responses

Response samples

Content type
application/json
{
  • "error": "invalid session: failed to find refresh token",
  • "error_code": "InvalidSession"
}

API Keys

View and manage API keys through the API Key provider.

List API keys

List API keys associated with a Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new API key

Create a new API key.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The API key to create.

name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "key": "string",
  • "name": "string",
  • "disabled": "string"
}

Retrieve information about an API key

Retrieve information about an API key.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

apiKeyId
required
string

The unique _id value of an API key

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "disabled": "string"
}

Delete an API key

Delete an API key.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

apiKeyId
required
string

The unique _id value of an API key

Responses

Enable an API key

Enable an API key.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

apiKeyId
required
string

The unique _id value of an API key

Responses

Disable an API key

Disable an API key.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

apiKeyId
required
string

The unique _id value of an API key

Responses

Applications

View and manage applications in an Atlas project.

List all App Services Apps in an Atlas project/group

List all App Services Apps within an Atlas project/group.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

query Parameters
product
string
Enum: "standard" "atlas" "data-api" "device-sync"

One or more specific App Services product types. If specified, this endpoint only returns Apps of the specified product type(s).

Most apps use the standard product type, which this endpoint returns by default. The atlas, data-api, and device-sync product types represent special apps for Atlas Triggers, Atlas Data API, and Atlas Device Sync that you can access through the Atlas UI.

You can specify multiple product types as a comma-separated list:

/groups/{groupId}/apps?product=atlas,data-api

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new app

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

query Parameters
defaults
boolean

Whether or not to create a default application.

product
string
Enum: "standard" "atlas" "data-api" "device-sync"

The App's product type. Apps use the standard product type by default. For most apps, you do not need to specify a product at all, or should specify standard.

The atlas, data-api, and device-sync product types represent special apps for Atlas Triggers, Atlas Data API, and Atlas Device Sync that you can access through the Atlas UI.

Request Body schema: application/json

The application to create.

name
string

The name of the application. Must begin with a letter and may only contain ASCII letters, numbers, underscores, and hyphens.

AwsDeploymentRegion (string) or AzureDeploymentRegion (string) or GcpDeploymentRegion (string) (CloudProviderRegionId)
location
string (DeploymentLocation)
Enum: "US-VA" "US-OR" "DE-FF" "IE" "AU" "IN-MB" "SG" "BR-SP"

The application's physical deployment location. This should agree with the more specific provider_region value. For example, an App with a provider_region of aws-us-west-2 maps to a location of US-OR.

deployment_model
string (DeploymentModel)
Enum: "GLOBAL" "LOCAL"

An application deployment model.

environment
string (NullableAppEnvironment)
Enum: "development" "testing" "qa" "production" ""

The application's environment. An empty string indicates that the app does not have a specified environment.

template_id
string

The id of an App Services template app to use as a base for the new app.

AtlasCluster (object) or AtlasFederatedInstance (object) (DataSource)

Responses

Request samples

Content type
application/json
{
  • "name": "MyApp",
  • "provider_region": "aws-us-east-1",
  • "location": "US-VA",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "template_id": "string",
  • "data_source": {
    }
}

Response samples

Content type
application/json
{
  • "name": "MyApp",
  • "provider_region": "aws-us-east-1",
  • "location": "US-VA",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "_id": "633209ffd3bd3478005d1bac",
  • "client_app_id": "myapp-abcde",
  • "domain_id": "63320a2b5f9de9a6e0a213e8",
  • "group_id": "5b2ec991973129243223a114",
  • "last_used": 1664224746,
  • "last_modified": 1656440824,
  • "product": "standard"
}

Get an app

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "name": "MyApp",
  • "provider_region": "aws-us-east-1",
  • "location": "US-VA",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "_id": "633209ffd3bd3478005d1bac",
  • "client_app_id": "myapp-abcde",
  • "domain_id": "63320a2b5f9de9a6e0a213e8",
  • "group_id": "5b2ec991973129243223a114",
  • "last_used": 1664224746,
  • "last_modified": 1656440824,
  • "product": "standard"
}

Delete an app

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Export an app as a zip file

The Export Endpoint is deprecated. Instead, call the Pull App Configuration Files endpoint with an Accept: application/zip header.

Export an application as a zip file.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
deployment
string
Example: deployment=6373362f01a569d5cd571c68

The _id of a specific deployment to export. If not specified, export the latest deployment.

source_control
boolean
Default: false

If true, the exported directory is suitable for automatic deployment from GitHub or other source control.

Cannot be used with the template query parameter.

template
boolean
Default: false

If true, the exported directory does not include any identifiers or other data that would tie the app to a specific deployment instance.

Cannot be used with the source_control query parameter.

version
string
Example: version=20210101

The configuration file schema version to export. This value corresponds to config_version in realm_config.json.

Responses

Pull App Configuration Files

Download the current App configuration. You can choose to download in two different formats:

  • A compressed zip file that contains the configuration file directory. This is most useful when you're working with the CLI, a version control system, or another environment based on the file system.

  • A single JSON object that contains the entire configuration. This is most useful when you're working with the API or another environment that can parse JSON.

You specify which format to download by setting the Accept header.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
{
  • "name": "string",
  • "provider_region": "aws-us-east-1",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "auth_providers": [
    ],
  • "custom_user_data": {
    },
  • "data_api_config": {
    },
  • "data_sources": [
    ],
  • "endpoints": [
    ],
  • "environments": {
    },
  • "functions": [
    ],
  • "graphql": {
    },
  • "hosting": {
    },
  • "https_endpoints": [
    ],
  • "log_forwarders": [
    ],
  • "schemas": [
    ],
  • "services": [
    ],
  • "sync": {
    },
  • "triggers": [
    ],
  • "values": [
    ]
}

Push App Configuration Files

Upload a new full App configuration. This operation overwrites the entire existing App configuration.

Note: If your App configuration includes any references to a Secret, you must create the Secret before you push the configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
name
required
string

The App's name.

required
AwsDeploymentRegion (string) or AzureDeploymentRegion (string) or GcpDeploymentRegion (string) (CloudProviderRegionId)
deployment_model
required
string (DeploymentModel)
Enum: "GLOBAL" "LOCAL"

An application deployment model.

environment
string (AppEnvironment)
Enum: "development" "testing" "qa" "production"

The App's environment tag. If not specified, the App has no environment tag.

required
Array of AnonymousAuthProvider (object) or EmailPasswordAuthProvider (object) or ApiKeyAuthProvider (object) or CustomJwtAuthProvider (object) or CustomFunctionAuthProvider (object) or AppleAuthProvider (object) or GoogleAuthProvider (object) or FacebookAuthProvider (object) (AuthProviderConstructor)
CustomUserDataConstructor (object) or null
DataApiConfig (object) or null
required
Array of AtlasClusterConstructor (object) or AtlasFederatedInstanceConstructor (object) (DataSourceConstructor)
required
Array of objects (EndpointConstructor)
required
object (AllEnvironmentValues)
required
Array of objects (FunctionConstructor)
required
object (GraphQLConstructor)
required
object (HostingConstructor)
required
Array of objects (ThirdPartyServiceConstructor)

[Deprecated] A list of legacy HTTP services. This is for backwards compatibility only.

required
Array of objects (LogForwarderConstructor)
required
Array of objects (FullSchema)
required
Array of objects (ThirdPartyServiceConstructor)

[Deprecated] A list of legacy third-party non-HTTP services. This is for backwards compatibility only.

required
object (FlexibleSync)
required
Array of DatabaseTrigger (object) or AuthenticationTrigger (object) or ScheduledTrigger (object) (TriggerConstructor)
required
Array of objects (ValueConstructor)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "provider_region": "aws-us-east-1",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "auth_providers": [
    ],
  • "custom_user_data": {
    },
  • "data_api_config": {
    },
  • "data_sources": [
    ],
  • "endpoints": [
    ],
  • "environments": {
    },
  • "functions": [
    ],
  • "graphql": {
    },
  • "hosting": {
    },
  • "https_endpoints": [
    ],
  • "log_forwarders": [
    ],
  • "schemas": [
    ],
  • "services": [
    ],
  • "sync": {
    },
  • "triggers": [
    ],
  • "values": [
    ]
}

Authentication Providers

View and manage authentication providers.

List authentication providers in a Atlas App Services App

List authentication providers within a Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an authentication provider

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
Any of
name
required
string

The name of the authentication provider. This value must be the same as the value of type.

Value: "anon-user"
type
required
string
Enum: "anon-user" "local-userpass" "api-key" "oauth2-apple" "oauth2-google" "oauth2-facebook" "custom-token" "custom-function"

The name of the authentication provider. For Anonymous authentication, this value is always anon-user.

Value: "anon-user"
disabled
boolean

If true, the auth provider is disabled. Users cannot log in through the provider until it is enabled.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "anon-user",
  • "type": "anon-user",
  • "disabled": true
}

Response samples

Content type
application/json
Example
{
  • "name": "anon-user",
  • "type": "anon-user",
  • "disabled": true,
  • "_id": "string"
}

Retrieve information about authentication provider

Retrieve information about one of an application's authentication providers.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

providerId
required
string

The unique _id value of an authentication provider

Responses

Response samples

Content type
application/json
Example
{
  • "name": "anon-user",
  • "type": "anon-user",
  • "disabled": true,
  • "_id": "string"
}

Delete an authentication provider

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

providerId
required
string

The unique _id value of an authentication provider

Responses

Update an authentication provider

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

providerId
required
string

The unique _id value of an authentication provider

Request Body schema: application/json
Any of
name
required
string

The name of the authentication provider. This value must be the same as the value of type.

Value: "anon-user"
type
required
string
Enum: "anon-user" "local-userpass" "api-key" "oauth2-apple" "oauth2-google" "oauth2-facebook" "custom-token" "custom-function"

The name of the authentication provider. For Anonymous authentication, this value is always anon-user.

Value: "anon-user"
disabled
boolean

If true, the auth provider is disabled. Users cannot log in through the provider until it is enabled.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "anon-user",
  • "type": "anon-user",
  • "disabled": true
}

Disable an authentication provider

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

providerId
required
string

The unique _id value of an authentication provider

Responses

Enable an authentication provider

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

providerId
required
string

The unique _id value of an authentication provider

Responses

Billing

View billed usage of your applications.

List group billing usage in a given period

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

query Parameters
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
Enum: "P31D" "PT1H"

Specifies the granularity of the query period, either P31D (31 day) or PT1H (1 hour). Default is P31D.

Responses

Response samples

Content type
application/json
{
  • "start": "string",
  • "end": "string",
  • "granularity": "string",
  • "group_id": "string",
  • "measurements": [
    ]
}

List app billing usage

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
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
Enum: "P31D" "PT1H"

Specifies the granularity of the query period, either P31D (31 day) or PT1H (1 hour). Default is P31D.

Responses

Response samples

Content type
application/json
{
  • "start": "string",
  • "end": "string",
  • "granularity": "string",
  • "group_id": "string",
  • "appId": "string",
  • "appName": "string",
  • "measurements": [
    ]
}

Custom User Data

Configure custom user data.

Get the Custom User Data Configuration

Get the Custom User Data configuration for an Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "database_name": "myapp",
  • "collection_name": "users",
  • "user_id_field": "user_account_id",
  • "enabled": true,
  • "mongo_service_id": "63c060ed32043ef4c93c2a9c",
  • "on_user_creation_function_id": "63c055d8019a6ab879f661d6"
}

Configure Custom User Data

Modify the Custom User Data configuration for an Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
database_name
string

The name of the database that contains custom user data.

collection_name
string

The name of the collection that contains custom user data.

user_id_field
string

The name of a field that appears in every custom user data document and that contains the user account ID of each document's corresponding user.

enabled
boolean

If true, custom user data is enabled.

mongo_service_id
string

The _id value of the linked MongoDB data source that contains custom user data.

See Get a Data Source.

on_user_creation_function_id
string

The _id value of a user creation function that runs whenever a new user registers.

Responses

Request samples

Content type
application/json
{
  • "database_name": "myapp",
  • "collection_name": "users",
  • "user_id_field": "user_account_id",
  • "enabled": true,
  • "mongo_service_id": "63c060ed32043ef4c93c2a9c",
  • "on_user_creation_function_id": "63c055d8019a6ab879f661d6"
}

Deployment

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:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  'https://services.cloud.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:

curl --request DELETE \
  --header 'Authorization: Bearer <access_token>' \
  'https://services.cloud.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. App Services 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:

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

Draft Conflicts

If you deploy changes through the API but have conflicting changes in a draft in the UI, your UI draft will become invalid and you will not be able to deploy it. You can download your UI draft by reviewing the draft in the Deployment page. You can use the download to deploy your changes in the appservices CLI or as a reference as you reapply changes in the UI.

List all available Atlas App cloud regions

Return a list of all supported cloud regions in which you can deploy an Atlas App.

Authorizations:
tokenAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the Deployment Configuration

See information about how your App deploys changes.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "ui_drafts_disabled": true,
  • "automatic_deployment": {
    },
  • "last_modified": 0
}

Configure Deployment

Modify an App's deployment configuration to customize how the App deploys changes.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
ui_drafts_disabled
required
boolean

If true, every change made in the Admin UI deploys automatically on save. If false, changes are grouped into a deployment draft that you deploy separately.

required
object

Configuration for automatic deployment methods

last_modified
number

The time this configuration was last modified represented by the number of seconds since the UNIX epoch.

Responses

Request samples

Content type
application/json
{
  • "ui_drafts_disabled": true,
  • "automatic_deployment": {
    },
  • "last_modified": 0
}

List recent deployments

Return the 25 most recent application deployments.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a deployment

Get information about a recent deployment of the application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

deploymentId
required
string

The _id value of an application deployment.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "app_id": "string",
  • "draft_id": "string",
  • "user_id": "string",
  • "deployed_at": 0,
  • "origin": "string",
  • "commit": "string",
  • "status": "string",
  • "status_error_message": "string",
  • "diff_url": "string",
  • "remote_location": "US-VA"
}

Redeploy a Deployment

Redeploy a previously-deployed version of an App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

deploymentId
required
string

The _id value of an application deployment.

Responses

Response samples

Content type
application/json
{
  • "error": "deployment not found",
  • "error_code": "DeploymentNotFound"
}

Get Current Deployment Draft

Return the current application deployment draft, if applicable.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user_id": "string",
  • "app": {
    }
}

Create a Deployment Draft

Create a new application deployment draft, if none exists.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user_id": "string",
  • "app": {
    }
}

Discard the specified deployment draft

Discard the specified application deployment draft.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

draftId
required
string

The unique _id value of a draft.

Responses

Deploy a deployment draft

Deploy the specified application deployment draft.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

draftId
required
string

The unique _id value of a draft.

Request Body schema: application/json
name
required
string

The name of the deployment. To deploy a draft without a name, use an empty string.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "app_id": "string",
  • "draft_id": "string",
  • "user_id": "string",
  • "deployed_at": 0,
  • "origin": "string",
  • "commit": "string",
  • "status": "string",
  • "status_error_message": "string",
  • "diff_url": "string",
  • "remote_location": "US-VA"
}

Diff a draft with the current deployment

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

draftId
required
string

The unique _id value of a draft.

Responses

Response samples

Content type
application/json
{
  • "diffs": [
    ],
  • "hosting_files_diff": {
    }
}

Get a Deployment Migration

Get metadata and status for the current deployment migration, if one exists.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "status": "started",
  • "message": "string",
  • "updated_at": "string",
  • "from": {
    },
  • "to": {
    }
}

Create a Deployment Migration

Start a new deployment migration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The deployment model and cloud provider region that the App should migrate to.

deployment_model
string (DeploymentModel)
Enum: "GLOBAL" "LOCAL"

An application deployment model.

AwsDeploymentRegion (string) or AzureDeploymentRegion (string) or GcpDeploymentRegion (string) (CloudProviderRegionId)

Responses

Request samples

Content type
application/json
{
  • "deployment_model": "LOCAL",
  • "provider_region": "aws-us-east-1"
}

Data API

Manage your app's generated Data API endpoints.

Construct a Data API Base URL

Data API requests use a base URL that's specific to your App and deployment model.

For a globally deployed app, the base URL has the following format:

https://data.mongodb-api.com/app/{ClientAppID}/endpoint/data/{DataAPIVersion}

A locally deployed app uses a similar base URL also includes the App's deployment region and cloud provider:

https://{Region}.{Cloud}.data.mongodb-api.com/app/{ClientAppID}/endpoint/data/{DataAPIVersion}

You can find an App's Region, Cloud, and ClientAppId in the App Configuration:

curl -X GET https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId} \
  -h 'Authorization: Bearer <AccessToken>'

You can see a list of all DataAPIVersion values supported by an App in the versions field of its Data API Configuration:

curl -X GET "https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/data_api/config" \
  -h 'Authorization: Bearer <AccessToken>'

For example, consider an App that has the following configuration:

{
  "client_app_id": "myapp-abcde",
  "deployment_model": "LOCAL",
  "provider_region": "aws-us-east-1",
  ...
}

This App would use the following base URL for Data API v1 requests:

https://us-east-1.aws.data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1

Get the Data API Configuration

Get your app's Data API configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "disabled": true,
  • "versions": [
    ],
  • "return_type": "JSON",
  • "create_user_on_auth": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_name": "string",
  • "can_evaluate": { }
}

Enable the Data API

Create your app's Data API configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A valid configuration object for the endpoint.

disabled
required
boolean
versions
required
Array of strings (DataApiVersion)
Items Value: "v1"
return_type
required
string (EndpointDataFormat)
Enum: "JSON" "EJSON"

The default data format returned by Data API endpoints.

create_user_on_auth
boolean
run_as_user_id
string

An application user's account ID. If defined, endpoints will always run as the specified user.

run_as_user_id_script_source
string

Stringified source code for a function that returns an application user's account ID. If defined, endpoints execute the function on every request and run as the user with the ID returned from the function.

validation_method
required
string
Enum: "NO_VALIDATION" "SECRET_AS_QUERY_PARAM" "VERIFY_PAYLOAD"
secret_name
string

If validation_method is set to "SECRET_AS_QUERY_PARAM" or "VERIFY_PAYLOAD", this is the name of the Secret that authorizes requests.

can_evaluate
object

A JSON expression that evaluates to true if an endpoint is allowed to run in response to an incoming request.

Responses

Request samples

Content type
application/json
{
  • "disabled": true,
  • "versions": [
    ],
  • "return_type": "JSON",
  • "create_user_on_auth": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_name": "string",
  • "can_evaluate": { }
}

Response samples

Content type
application/json
{
  • "disabled": true,
  • "versions": [
    ],
  • "return_type": "JSON",
  • "create_user_on_auth": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_name": "string",
  • "can_evaluate": { }
}

Modify the Data API

Update your app's Data API configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A valid configuration object for the endpoint.

disabled
required
boolean
versions
required
Array of strings (DataApiVersion)
Items Value: "v1"
return_type
required
string (EndpointDataFormat)
Enum: "JSON" "EJSON"

The default data format returned by Data API endpoints.

create_user_on_auth
boolean
run_as_user_id
string

An application user's account ID. If defined, endpoints will always run as the specified user.

run_as_user_id_script_source
string

Stringified source code for a function that returns an application user's account ID. If defined, endpoints execute the function on every request and run as the user with the ID returned from the function.

validation_method
required
string
Enum: "NO_VALIDATION" "SECRET_AS_QUERY_PARAM" "VERIFY_PAYLOAD"
secret_name
string

If validation_method is set to "SECRET_AS_QUERY_PARAM" or "VERIFY_PAYLOAD", this is the name of the Secret that authorizes requests.

can_evaluate
object

A JSON expression that evaluates to true if an endpoint is allowed to run in response to an incoming request.

Responses

Request samples

Content type
application/json
{
  • "disabled": true,
  • "versions": [
    ],
  • "return_type": "JSON",
  • "create_user_on_auth": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_name": "string",
  • "can_evaluate": { }
}

List Data API versions

List all possible Data API versions.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • "v1"
]

Dependencies

Manage your application's external dependencies.

List external dependencies

List external dependencies uploaded to the Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "location": "string",
  • "user_id": "string",
  • "last_modified": 0,
  • "dependencies_list": [
    ]
}

Endpoints

View and manage your app's custom HTTPS endpoints.

Construct a Custom HTTPS Endpoint Base URL

HTTPS Endpoint requests use a base URL that's specific to your App and deployment model.

For a globally deployed app, the base URL has the following format:

https://data.mongodb-api.com/app/{ClientAppID}/endpoint

A locally deployed app uses a similar base URL also includes the App's deployment region and cloud provider:

https://{Region}.{Cloud}.data.mongodb-api.com/app/{ClientAppID}/endpoint

You can find an App's Region, Cloud, and ClientAppId by calling the Get an App endpoint:

curl -X GET https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId} \
  -h 'Authorization: Bearer <AccessToken>'

For example, consider an App that has the following configuration:

{
  "client_app_id": "myapp-abcde",
  "deployment_model": "LOCAL",
  "provider_region": "aws-us-east-1",
  ...
}

This App would use the following base URL for incoming custom HTTPS endpoint requests:

https://us-east-1.aws.data.mongodb-api.com/app/myapp-abcde/endpoint

Get all endpoints

Get all endpoint configurations.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an endpoint

Create a new endpoint.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A valid configuration object for the new endpoint.

route
required
string
http_method
required
string
Enum: "GET" "POST" "PUT" "PATCH" "DELETE" "*"
function_id
required
string

The endpoint function's unique ID.

validation_method
required
string
Enum: "NO_VALIDATION" "SECRET_AS_QUERY_PARAM" "VERIFY_PAYLOAD"
secret_id
string

If validation_method is set to "SECRET_AS_QUERY_PARAM" or "VERIFY_PAYLOAD", this is the _id of the Secret that authorizes requests.

return_type
required
string (EndpointDataFormat)
Enum: "JSON" "EJSON"

The default data format returned by custom HTTPS endpoints.

respond_result
required
boolean
fetch_custom_user_data
boolean
create_user_on_auth
boolean
disabled
required
boolean
_id
string

The endpoint's unique ID.

Responses

Request samples

Content type
application/json
{
  • "route": "string",
  • "http_method": "GET",
  • "function_id": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_id": "string",
  • "return_type": "JSON",
  • "respond_result": true,
  • "fetch_custom_user_data": true,
  • "create_user_on_auth": true,
  • "disabled": true,
  • "_id": "string"
}

Response samples

Content type
application/json
{
  • "route": "string",
  • "http_method": "GET",
  • "function_id": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_id": "string",
  • "return_type": "JSON",
  • "respond_result": true,
  • "fetch_custom_user_data": true,
  • "create_user_on_auth": true,
  • "disabled": true,
  • "_id": "string",
  • "function_name": "string"
}

Get an endpoint

Get a specific endpoint's configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

endpointId
required
string

The unique _id value of an endpoint

Responses

Response samples

Content type
application/json
{
  • "route": "string",
  • "http_method": "GET",
  • "function_id": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_id": "string",
  • "return_type": "JSON",
  • "respond_result": true,
  • "fetch_custom_user_data": true,
  • "create_user_on_auth": true,
  • "disabled": true,
  • "_id": "string",
  • "function_name": "string"
}

Modify an endpoint

Modify an existing endpoint configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

endpointId
required
string

The unique _id value of an endpoint

Request Body schema: application/json

A valid, updated configuration object for the endpoint.

route
required
string
http_method
required
string
Enum: "GET" "POST" "PUT" "PATCH" "DELETE" "*"
function_id
required
string

The endpoint function's unique ID.

validation_method
required
string
Enum: "NO_VALIDATION" "SECRET_AS_QUERY_PARAM" "VERIFY_PAYLOAD"
secret_id
string

If validation_method is set to "SECRET_AS_QUERY_PARAM" or "VERIFY_PAYLOAD", this is the _id of the Secret that authorizes requests.

return_type
required
string (EndpointDataFormat)
Enum: "JSON" "EJSON"

The default data format returned by custom HTTPS endpoints.

respond_result
required
boolean
fetch_custom_user_data
boolean
create_user_on_auth
boolean
disabled
required
boolean
_id
string

The endpoint's unique ID.

Responses

Request samples

Content type
application/json
{
  • "route": "string",
  • "http_method": "GET",
  • "function_id": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_id": "string",
  • "return_type": "JSON",
  • "respond_result": true,
  • "fetch_custom_user_data": true,
  • "create_user_on_auth": true,
  • "disabled": true,
  • "_id": "string"
}

Response samples

Content type
application/json
{
  • "route": "string",
  • "http_method": "GET",
  • "function_id": "string",
  • "validation_method": "NO_VALIDATION",
  • "secret_id": "string",
  • "return_type": "JSON",
  • "respond_result": true,
  • "fetch_custom_user_data": true,
  • "create_user_on_auth": true,
  • "disabled": true,
  • "_id": "string",
  • "function_name": "string"
}

Delete an endpoint

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

endpointId
required
string

The unique _id value of an endpoint

Responses

Response samples

Content type
application/json
{ }

Event Subscriptions

View your app's active event subscriptions. These monitor real-time events, e.g. from a MongoDB change stream, to power application services like Triggers and Device Sync.

List Event Subscriptions

Get all event subscriptions.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
type
string
Enum: "DATABASE" "AUTHENTICATION" "SCHEDULED" "SYNCTRANSLATOR"

The type of event subscription to return.

  • DATABASE: Return Database Triggers
  • AUTHENTICATION: Return Authentication Triggers
  • SCHEDULED: Return Scheduled Triggers
  • SYNCTRANSLATOR: Return Device Sync translators

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an Event Subscription

Return information about an event subscription.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

eventSubscriptionId
required
string

The unique _id value of an event subscription.

Responses

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "name": "onNewEmployee",
  • "type": "DATABASE",
  • "function_id": "5eea9ca4ca0e356e2c2a148a",
  • "config": {
    }
}

Get the Latest Event Subscription Execution

Return information about the most recent execution of an event subscription.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

eventSubscriptionId
required
string

The unique _id value of an event subscription.

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "resource_id": { },
  • "completed_at": { },
  • "cluster_time": { }
}

Environments

View and manage your app's environment and environment values.

Set the App Environment

Set the App's active environment

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
environment
string (NullableAppEnvironment)
Enum: "development" "testing" "qa" "production" ""

The application's environment. An empty string indicates that the app does not have a specified environment.

Responses

Request samples

Content type
application/json
{
  • "environment": "production"
}

Response samples

Content type
application/json
{
  • "name": "MyApp",
  • "provider_region": "aws-us-east-1",
  • "location": "US-VA",
  • "deployment_model": "GLOBAL",
  • "environment": "production",
  • "_id": "633209ffd3bd3478005d1bac",
  • "client_app_id": "myapp-abcde",
  • "domain_id": "63320a2b5f9de9a6e0a213e8",
  • "group_id": "5b2ec991973129243223a114",
  • "last_used": 1664224746,
  • "last_modified": 1656440824,
  • "product": "standard"
}

List All Environment Values

Get basic information about all environment values in the App. Results do not include the environment-specific values. For details on a specific environment, call Get an Environment Value.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an Environment Value

Define a new environment value.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
_id
string

The environment value's internal ID

name
string

The environment value name

last_modified
number

The time this configuration was last modified represented by the number of seconds since the UNIX epoch.

object

An object that maps environment names to values. The environment value resolves to the current active environment's mapped value.

If no value is mapped to the current active environment, the environment value resolves to undefined.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "last_modified": 0,
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "last_modified": 0
}

Get an Environment Value

Get details about a specific environment value

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

environmentValueId
required
string

The _id value of an environment value.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "last_modified": 0,
  • "values": {
    }
}

Modify an Environment Value

Modify an existing environment value

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

environmentValueId
required
string

The _id value of an environment value.

Request Body schema: application/json
_id
string

The environment value's internal ID

name
string

The environment value name

last_modified
number

The time this configuration was last modified represented by the number of seconds since the UNIX epoch.

object

An object that maps environment names to values. The environment value resolves to the current active environment's mapped value.

If no value is mapped to the current active environment, the environment value resolves to undefined.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "last_modified": 0,
  • "values": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "last_modified": 0
}

Delete an Environment Value

Delete an existing environment value

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

environmentValueId
required
string

The _id value of an environment value.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "EnvironmentValueNotFound"
}

Functions

View and manage your app's functions.

Execute a function

Execute a function for testing.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
user_id
required
string

The user as which to execute the function. Either user_id or run_as_system is required. You cannot specify both.

run_as_system
required
boolean

Determine whether or not to run as system user. Either run_as_system or user_id is required. You cannot specify both.

Request Body schema: application/json

The function to execute.

service
string

The service to use when calling this function.

name
required
string

The name of the function you want to run.

arguments
Array of strings

Any arguments that your function needs.

Responses

Request samples

Content type
application/json
{
  • "service": "string",
  • "name": "string",
  • "arguments": [
    ]
}

Response samples

Content type
application/json
{
  • "error": { },
  • "logs": null,
  • "result": { },
  • "stats": {
    }
}

Execute a function's source code for testing

Execute a function's source code for testing.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
user_id
required
string

The user as which to execute the function. Either user_id or run_as_system is required. You cannot specify both.

run_as_system
required
boolean

Determine whether or not to run as system user. Either run_as_system or user_id is required. You cannot specify both.

Request Body schema: application/json

The source to execute.

eval_source
string

This JSON expression must evaluate to true before the function may run. If this field is blank, it will evaluate to true.

source
required
string

Responses

Request samples

Content type
application/json
{
  • "eval_source": "string",
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "error": { },
  • "logs": null,
  • "result": { },
  • "stats": {
    }
}

List Functions

List Functions.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Function

Create a new Function.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The function to create

can_evaluate
object

A JSON expression that evaluates to true if the Function is allowed to run in response to an incoming request.

name
required
string

A unique name for the Function.

private
required
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
required
string

The stringified source code for the function. The code must be valid ES6.

run_as_system
boolean

If true, the function executes with full privileges, bypassing rules on all services.

run_as_user_id
string

An application user's account ID. If defined, endpoints will always run as the specified user. Cannot be used with run_as_user_id_script_source.

run_as_user_id_script_source
string

The stringified source code for a function that returns an application user's account ID. If defined, endpoints execute the function on every request and run as the user with the ID returned from the function. Cannot be used with run_as_user_id.

Responses

Request samples

Content type
application/json
{
  • "can_evaluate": { },
  • "name": "string",
  • "private": true,
  • "source": "string",
  • "run_as_system": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string"
}

Retrieve a Function

Retrieve a Function.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

functionId
required
string

The unique _id value of a function.

Responses

Response samples

Content type
application/json
{
  • "can_evaluate": { },
  • "name": "string",
  • "private": true,
  • "source": "string",
  • "run_as_system": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string"
}

Delete a Function

Delete a Function.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

functionId
required
string

The unique _id value of a function.

Responses

Update a Function

Update a Function.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

functionId
required
string

The unique _id value of a function.

Responses

Response samples

Content type
application/json
{
  • "can_evaluate": { },
  • "name": "string",
  • "private": true,
  • "source": "string",
  • "run_as_system": true,
  • "run_as_user_id": "string",
  • "run_as_user_id_script_source": "string"
}

GraphQL API

Configure and run GraphQL API operations.

Run a query or mutation

Run a query or mutation as a system user that bypasses authentication and data access rules. You can access metadata about your API, including its schema, with an introspection query.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
query
required
string

A stringified .graphql file that contains one or more valid GraphQL operations for your API. If more than one operation is defined, you must specify which operation to run in operationName.

variables
string

A stringified JSON object where each field name maps a value to a variable in the specified operation.

operationName
string

The name of the GraphQL operation specified in query to run.

Responses

Request samples

Content type
application/json
{
  • "query": "query AllTasks { tasks(query: { status: $status }) { _id owner } }",
  • "variables": "{ \"status\": \"complete\" }",
  • "operationName": "AllTasks"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "errors": [
    ]
}

Get GraphQL API Configuration

Get your app's GraphQL API configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "use_natural_pluralization": true,
  • "disable_schema_introspection": true
}

Update GraphQL API Configuration

Update your app's GraphQL API configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
use_natural_pluralization
boolean

If true, generated schema type names use common English pluralization whenever possible.

If false, or if a natural pluralization cannot be determined, then plural types use the singular type name with an "s" appended to the end.

You cannot change this value after you create your App. This value is true for all new Apps.

disable_schema_introspection
boolean

If true, the GraphQL API blocks introspection queries from clients.

Responses

Request samples

Content type
application/json
{
  • "use_natural_pluralization": true,
  • "disable_schema_introspection": true
}

Get all custom resolvers

Get all custom resolver configurations from your app's GraphQL API.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a custom resolver

Create a new custom resolver.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
on_type
required
string

The name of the resolver's parent type. This can be "Query", "Mutation", or the name of a generated type if this is a computed property.

field_name
required
string

The name of the custom resolver field that appears in the GraphQL schema.

string or object

The type of the custom resolver's input parameter. This can be a scalar, the name of an existing generated type, or a custom JSON schema object. If undefined, the resolver does not accept an input.

input_type_format
string
Enum: "scalar" "scalar-list" "generated" "generated-list" "custom"

The kind of input type the custom resolver uses. This value must agree with the value of input_type:

  • A scalar input type must use "scalar" or "scalar-list"
  • A generated input type must use "generated" or "generated-list"
  • A custom input type must use "custom"

If undefined, the resolver does not accept an input.

string or object

The type of the value returned by the custom resolver. This can be a scalar, the name of an existing generated type, or a custom JSON schema object.

If undefined, the resolver returns a DefaultPayload object:

type DefaultPayload {
  status: String!
}
payload_type_format
string
Enum: "scalar" "scalar-list" "generated" "generated-list" "custom"

The kind of payload type the custom resolver uses. This value must agree with the value of payload_type:

  • A scalar payload type must use "scalar" or "scalar-list"
  • A generated payload type must use "generated" or "generated-list"
  • A custom payload type must use "custom"

If undefined, the resolver returns a DefaultPayload object.

_id
required
string

The custom resolver's unique ID.

function_id
required
string

The resolver function's unique ID.

Responses

Request samples

Content type
application/json
{
  • "on_type": "string",
  • "field_name": "string",
  • "input_type": "string",
  • "input_type_format": "scalar",
  • "payload_type": "string",
  • "payload_type_format": "scalar",
  • "_id": "string",
  • "function_id": "string"
}

Response samples

Content type
application/json
{
  • "on_type": "string",
  • "field_name": "string",
  • "input_type": "string",
  • "input_type_format": "scalar",
  • "payload_type": "string",
  • "payload_type_format": "scalar",
  • "_id": "string",
  • "function_id": "string"
}

Get a custom resolver

Get a specific custom resolver configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

customResolverId
required
string

The unique _id value of a custom resolver.

Responses

Response samples

Content type
application/json
{
  • "on_type": "string",
  • "field_name": "string",
  • "input_type": "string",
  • "input_type_format": "scalar",
  • "payload_type": "string",
  • "payload_type_format": "scalar",
  • "_id": "string",
  • "function_id": "string"
}

Modify a custom resolver

Modify an existing custom resolver configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

customResolverId
required
string

The unique _id value of a custom resolver.

Request Body schema: application/json

A valid, updated custom resolver configuration object.

on_type
required
string

The name of the resolver's parent type. This can be "Query", "Mutation", or the name of a generated type if this is a computed property.

field_name
required
string

The name of the custom resolver field that appears in the GraphQL schema.

string or object

The type of the custom resolver's input parameter. This can be a scalar, the name of an existing generated type, or a custom JSON schema object. If undefined, the resolver does not accept an input.

input_type_format
string
Enum: "scalar" "scalar-list" "generated" "generated-list" "custom"

The kind of input type the custom resolver uses. This value must agree with the value of input_type:

  • A scalar input type must use "scalar" or "scalar-list"
  • A generated input type must use "generated" or "generated-list"
  • A custom input type must use "custom"

If undefined, the resolver does not accept an input.

string or object

The type of the value returned by the custom resolver. This can be a scalar, the name of an existing generated type, or a custom JSON schema object.

If undefined, the resolver returns a DefaultPayload object:

type DefaultPayload {
  status: String!
}
payload_type_format
string
Enum: "scalar" "scalar-list" "generated" "generated-list" "custom"

The kind of payload type the custom resolver uses. This value must agree with the value of payload_type:

  • A scalar payload type must use "scalar" or "scalar-list"
  • A generated payload type must use "generated" or "generated-list"
  • A custom payload type must use "custom"

If undefined, the resolver returns a DefaultPayload object.

_id
required
string

The custom resolver's unique ID.

function_id
required
string

The resolver function's unique ID.

Responses

Request samples

Content type
application/json
{
  • "on_type": "string",
  • "field_name": "string",
  • "input_type": "string",
  • "input_type_format": "scalar",
  • "payload_type": "string",
  • "payload_type_format": "scalar",
  • "_id": "string",
  • "function_id": "string"
}

Delete a custom resolver

Delete an existing custom resolver configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

customResolverId
required
string

The unique _id value of a custom resolver.

Responses

Get validation settings

Get the current validation level and action for reads and writes.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "read_validation_action": "ERROR",
  • "read_validation_level": "STRICT",
  • "write_validation_action": "ERROR",
  • "write_validation_level": "STRICT"
}

Modify validation settings

Set the validation level and action for reads and writes.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The updated validation levels and actions.

read_validation_action
string (GraphQLValidationAction)
Enum: "ERROR" "WARN"
read_validation_level
string (GraphQLValidationLevel)
Enum: "STRICT" "OFF"
write_validation_action
string (GraphQLValidationAction)
Enum: "ERROR" "WARN"
write_validation_level
string (GraphQLValidationLevel)
Enum: "STRICT" "OFF"

Responses

Request samples

Content type
application/json
{
  • "read_validation_action": "ERROR",
  • "read_validation_level": "STRICT",
  • "write_validation_action": "ERROR",
  • "write_validation_level": "STRICT"
}

Hosting

Manage your application's hosted files.

Asset Metadata Document Example

Asset metadata documents describe hosted asset files.

{
  "path": "<Asset Resource Path>",
  "hash": "<Asset MD5 Checksum Hash>",
  "size": <File size in bytes>,
  "attrs": [
      {
        "name": "<Metadata Attribute Name>",
        "value": "<Metadata Attribute Value>",
      }
  ]
}

Get Hosting Configuration

Returns the current hosting configuration. Hosting is active if the response includes status: "setup_ok".

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "status": "setup_ok",
  • "default_domain": {
    }
}

Enable/Disable Hosting

Enable or disable App Services Hosting for your app. Changes to hosting can take up to 15 minutes to take effect. This endpoint does not notify you when the changes have taken effect, only that the change operation was successfully received by the server.

You can see if the hosting enablement/disablement is complete by calling the Get Hosting Configuration endpoint.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
enabled
boolean

Set to true to enable App Services Hosting. Set to false to disable App Services Hosting.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

List all hosted assets

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Move or copy a hosted asset

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

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

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

Request samples

Content type
application/json
{
  • "move_from": "string",
  • "move_to": "string",
  • "copy_from": "string",
  • "copy_to": "string"
}

Retrieve metadata for a specific hosted asset

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
path
required
string

The resource path of a hosted asset.

prefix
string

Return only those assets where the resource path begins with the specified prefix.

Responses

Response samples

Content type
application/json
{
  • "appId": "string",
  • "last_modified": 0,
  • "url": "string",
  • "path": "string",
  • "size": 0,
  • "attrs": [
    ],
  • "hash": "string"
}

Upload or replace a hosted asset

Upload or replace a hosted asset at a specific resource path.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
path
required
string

The resource path of a hosted asset.

Request Body schema: application/json

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

object (AssetMetadata)

An asset metadata document (encoded as JSON).

file
string <binary>

The asset file to upload (encoded as binary).

Responses

Request samples

Content type
application/json
{
  • "meta": {
    },
  • "file": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Update the metadata attributes of a hosted asset

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
path
required
string

The resource path of a hosted asset.

Request Body schema: application/json

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

Array of objects (MetadataAttribute)

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Logs

Access your application's logs.

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:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://services.cloud.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:

curl --request GET \
  --header 'Authorization: Bearer <access_token>' \
  'https://services.cloud.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.

Retrieve App Services logs

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
co_id
string

Return only log messages associated with the given request Correlation ID.

errors_only
boolean

The value of this field does not matter. If included in the request, this endpoint only returns error logs (even if the value is set to false). If this field is excluded from the request, this endpoint only returns non-error logs.

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 [ 1 .. 100 ]

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.

type
string
Enum: "TRIGGER_FAILURE" "TRIGGER_ERROR_HANDLER" "DB_TRIGGER" "AUTH_TRIGGER" "SCHEDULED_TRIGGER" "FUNCTION" "SERVICE_FUNCTION" "STREAM_FUNCTION" "SERVICE_STREAM_FUNCTION" "AUTH" "WEBHOOK" "ENDPOINT" "PUSH" "API" "API_KEY" "GRAPHQL" "SYNC_CONNECTION_START" "SYNC_CONNECTION_END" "SYNC_SESSION_START" "SYNC_SESSION_END" "SYNC_CLIENT_WRITE" "SYNC_ERROR" "SYNC_OTHER" "SCHEMA_ADDITIVE_CHANGE" "SCHEMA_GENERATION" "SCHEMA_VALIDATION" "LOG_FORWARDER"

The kind of log you would like to retrieve.

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ],
  • "nextEndDate": "string",
  • "nextSkip": 0
}

Log Forwarding

View and manage your application's log forwarders.

List log forwarders.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A log forwarder configuration

name
required
string
disabled
required
boolean
log_types
required
Array of strings (LogType)
Items Enum: "auth" "endpoint" "function" "graphql" "push" "schema" "service" "sync" "trigger" "trigger_error_handler"
log_statuses
required
Array of strings (LogStatus)
Items Enum: "error" "success"
required
object (LogForwardingPolicy)
required
object (LogForwardingAction)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "disabled": true,
  • "log_types": [
    ],
  • "log_statuses": [
    ],
  • "policy": {
    },
  • "action": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "disabled": true,
  • "log_types": [
    ],
  • "log_statuses": [
    ],
  • "policy": {
    },
  • "action": {
    }
}

Get a specific log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

forwarderId
required
string

The _id ObjectID of a log forwarder.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "disabled": true,
  • "log_types": [
    ],
  • "log_statuses": [
    ],
  • "policy": {
    },
  • "action": {
    }
}

Update a log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

forwarderId
required
string

The _id ObjectID of a log forwarder.

Request Body schema: application/json

A log forwarder configuration

name
required
string
disabled
required
boolean
log_types
required
Array of strings (LogType)
Items Enum: "auth" "endpoint" "function" "graphql" "push" "schema" "service" "sync" "trigger" "trigger_error_handler"
log_statuses
required
Array of strings (LogStatus)
Items Enum: "error" "success"
required
object (LogForwardingPolicy)
required
object (LogForwardingAction)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "disabled": true,
  • "log_types": [
    ],
  • "log_statuses": [
    ],
  • "policy": {
    },
  • "action": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "disabled": true,
  • "log_types": [
    ],
  • "log_statuses": [
    ],
  • "policy": {
    },
  • "action": {
    }
}

Delete a log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

forwarderId
required
string

The _id ObjectID of a log forwarder.

Responses

Enable a log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

forwarderId
required
string

The _id ObjectID of a log forwarder.

Responses

Disable a log forwarder.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

forwarderId
required
string

The _id ObjectID of a log forwarder.

Responses

Metrics

View Atlas App Services metrics.

Retrieve App Services metrics

Retrieves a variety of metrics, including: Compute Time, Data Transfer, Sync Minutes, Requests Succeeded, Requests Failed. For a complete list of available metrics, see App Services Metrics Reference.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
start
required
string

The ISO-8601 date and time of the start of the query period (e.g. "2022-10-27T14:01:01Z").

end
required
string

The ISO-8601 date and time of the end of the query period (e.g. "2022-12-27T14:01:01Z").

granularity
required
string

Specifies the granularity of the query period as an ISO-8601 duration value. Examples include "P31D" (31 day), "PT1H" (1 hour), and "PT5M" (5 minutes).

metrics
string
Enum: "ACTIVE_OPEN_SYNC_SESSIONS" "AUTH_EGRESS_BYTES" "AUTH_FAILED_REQUESTS" "AUTH_RESPONSE_MS" "AUTH_SUCCESSFUL_LOGIN" "AUTH_SUCCESSFUL_REQUESTS" "AUTH_TOTAL_USERS" "ENDPOINTS_COMPUTE_MS" "ENDPOINTS_EGRESS_BYTES" "ENDPOINTS_FAILED_REQUEST" "ENDPOINTS_RESPONSE_MS" "ENDPOINTS_SUCCESSFUL_REQUESTS" "GRAPHQL_RESPONSE_MS" "GRAPHQL_COMPUTE_MS" "GRAPHQL_EGRESS_BYTES" "GRAPHQL_FAILED_REQUESTS" "GRAPHQL_SUCCESSFUL_REQUESTS" "LF_RESPONSE_MS" "OVERALL_COMPUTE_MS" "OVERALL_EGRESS_BYTES" "OVERALL_FAILED_REQUESTS" "OVERALL_SUCCESSFUL_REQUESTS" "OVERALL_SYNC_MINUTES" "SDK_COMPUTE_MS" "SDK_EGRESS_BYTES" "SDK_FAILED_REQUESTS" "SDK_FNS_RESPONSE_MS" "SDK_MQL_COMPUTE_MS" "SDK_MQL_EGRESS_BYTES" "SDK_MQL_FAILED_REQUESTS" "SDK_MQL_RESPONSE_MS" "SDK_MQL_SUCCESSFUL_REQUESTS" "SDK_SUCCESSFUL_REQUESTS" "SYNC_CLIENT_BOOTSTRAP_MS" "SYNC_CLIENT_UPLOADS_INVALID" "SYNC_CURRENT_OPLOG_LAG_MS_SUM" "SYNC_EGRESS_BYTES" "SYNC_FAILED_REQUESTS" "SYNC_HISTORY_WRITE_MS" "SYNC_MINUTES" "SYNC_NUM_INTEGRATION_ATTEMPTS" "SYNC_NUM_UNSYNCABLE_DOC" "SYNC_OT_MS" "SYNC_SESSIONS_ENDED" "SYNC_SESSIONS_STARTED" "SYNC_SUCCESSFUL_REQUESTS" "SYNC_UPLOAD_PROPS_MS" "TRIGGERS_COMPUTE_MS" "TRIGGERS_CURRENT_OPLOG_LAG_MS_SUM" "TRIGGERS_EGRESS_BYTES" "TRIGGERS_FAILED_REQUESTS" "TRIGGERS_RESPONSE_MS" "TRIGGERS_SUCCESSFUL_REQUESTS"

The name of the metric to filter by. For detailed information on the available metrics and their units, see App Services Metrics Reference.

Responses

Response samples

Content type
application/json
{
  • "measurements": [
    ],
  • "app_id": "string",
  • "app_name": "string",
  • "group_id": "string",
  • "start": "2022-10-27T14:01:01Z",
  • "end": "2022-12-27T14:01:01Z",
  • "granularity": "string"
}

Rules

View and manage your application's data access rules.

Get all rules

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a rule

Create a data access rule.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json

The rule to create.

One of
_id
string

The rule's unique ObjectId identifier.

Array of objects (Role)

A list of data access roles.

Array of objects (Filter)

A list of filters for incoming operations.

database
required
string

The name of a database in the linked data source.

collection
required
string

The name of a collection in the specified database.

Responses

Request samples

Content type
application/json
Example
{
  • "_id": "string",
  • "roles": [
    ],
  • "filters": [
    ],
  • "database": "string",
  • "collection": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string"
}

Get a rule

Get a specific data access rule.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

ruleId
required
string

The unique _id value of a rule.

Responses

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "roles": [
    ],
  • "filters": [
    ],
  • "database": "string",
  • "collection": "string"
}

Delete a rule

Delete a data access rule.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

ruleId
required
string

The unique _id value of a rule.

Responses

Update a rule

Update a data access rule.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

ruleId
required
string

The unique _id value of a rule.

Request Body schema: application/json

The new state of the rule.

One of
_id
string

The rule's unique ObjectId identifier.

Array of objects (Role)

A list of data access roles.

Array of objects (Filter)

A list of filters for incoming operations.

database
required
string

The name of a database in the linked data source.

collection
required
string

The name of a collection in the specified database.

Responses

Request samples

Content type
application/json
Example
{
  • "_id": "string",
  • "roles": [
    ],
  • "filters": [
    ],
  • "database": "string",
  • "collection": "string"
}

Get default roles and filters

Get the current default roles and filters.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ],
  • "filters": [
    ]
}

Create default roles and filters

Create default roles and filters for a data source.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json

A default rule configuration object.

Array of objects (RoleConstructor)

An ordered list of default user roles.

Array of objects (FilterConstructor)

A list of default query filters.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ],
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "roles": [
    ],
  • "filters": [
    ]
}

Update default roles and filters

Modify the default roles and filters of a data source.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json

The updated default rule configuration object.

_id
required
string

The default rule's unique ObjectId identifier.

Array of objects (Role)

An ordered list of default user roles.

Array of objects (Filter)

A list of default query filters.

Responses

Request samples

Content type
application/json
{
  • "roles": [
    ],
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "default rule does not exist"
}

Delete default roles and filters

Delete the default roles and filters of a data source.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
{
  • "error": "default rule does not exist for app service"
}

Schemas

View and manage your application's schemas.

Sample & Validate Documents

Query a subset of documents in a collection and validate each match against a schema.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

datasourceId
required
string

The unique _id value of a MongoDB data source.

Request Body schema: application/json
database_name
required
string

The name of the database that contains the collection to validate.

collection_name
required
string

The name of the collection to validate.

from_schema
required
object

The EJSON schema to validate sampled documents against.

query
object
Default: {}

A MongoDB query that matches documents in the collection. The result of running this query is the sample population. Use this to narrow the sample to a subset of documents in the collection.

limit
number
Default: 10000

The maximum number of documents to sample.

sort
object
Default: {}

A MongoDB sort for the collection. Use this to determine which end of a range query to start sampling from.

Responses

Request samples

Content type
application/json
{
  • "database_name": "string",
  • "collection_name": "string",
  • "from_schema": { },
  • "query": { },
  • "limit": 10000,
  • "sort": { }
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "total_processed_count": 0,
  • "total_error_count": 0
}

List schemas

List all defined schemas.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a schema

Define a new schema for a linked collection. When creating a schema with this endpoint, ensure that the JSON payload is completely unescaped. Incorrectly escaped JSON formats can lead to errors.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
required
object (SchemaMetadata)

Metadata that describes which linked collection the schema applies to.

object (SchemaDefinition)

A valid schema for the collection.

object (SchemaRelationships)

Relationships to foreign collections. Each field name is a property in the schema. The corresponding value is a relationship definition for that field.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "schema": {
    },
  • "relationships": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "metadata": {
    }
}

Get a schema

Get a specific schema by its _id value.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

schemaId
required
string

The unique _id value of a schema.

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "schema": {
    },
  • "relationships": {
    }
}

Update a schema

Replace an existing schema with a new one.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

schemaId
required
string

The unique _id value of a schema.

Request Body schema: application/json
object (SchemaMetadata)

Metadata that describes which linked collection the schema applies to.

object (SchemaDefinition)

A valid schema for the collection.

object (SchemaRelationships)

Relationships to foreign collections. Each field name is a property in the schema. The corresponding value is a relationship definition for that field.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "schema": {
    },
  • "relationships": {
    }
}

Delete a schema

Delete a specific schema by its _id value.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

schemaId
required
string

The unique _id value of a schema.

Responses

Get Null Type Schema Validation Setting

Check if null type schema validation is enabled.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "enabled": true
}

Set Null Type Schema Validation Setting

Enable or disable null type schema validation.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Secrets

View and manage your application's secrets.

List secrets

List secrets associated with a Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Secret

Create a new Secret.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The Secret to create.

name
required
string
value
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string"
}

Modify a Secret

Modify a Secret associated with a Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

secretId
required
string

The unique _id value of a secret.

Request Body schema: application/json

The modified value of the Secret.

_id
string
name
required
string
value
required
string

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "name": "string",
  • "value": "string"
}

Delete a Secret

Delete a Secret associated with a Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

secretId
required
string

The unique _id value of a secret.

Responses

Security

Configure your application's security.

List allowed HTTP origins

List the allowed HTTP origins from which App Services should allow requests.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Set allowed HTTP origins

Set the allowed HTTP origins from which App Services should allow requests.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A list of HTTP origins.

Array
string

An HTTP origin. Must be of the form <scheme>://<host>[:port].

Responses

Request samples

Content type
application/json
[
  • "string"
]

List the allowed entries in the Access List

List the allowed entries in the Access List of your Atlas App Services App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an IP address or CIDR block in the Access List

Create an IP address or CIDR block in the Access List for your App Services app.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The IP Access List entry to create.

address
required
string

The value of the IP address or CIDR block.

comment
string

An optional comment included in the Access List entry.

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "address": "string",
  • "ip": "string",
  • "network": "string",
  • "comment": "string"
}

Modify an IP address or CIDR block in the Access List

Modify an IP address or CIDR block in the Access List of your App Services app

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

ipId
required
string

The IP address entry denoted by ip_id with the information given in the request body

Request Body schema: application/json

The updated value of the IP Access List entry.

address
required
string

The modified value of the IP address or CIDR block.

comment
string

An optional comment included in the Access List entry.

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "address": "string",
  • "ip": "string",
  • "network": "string",
  • "comment": "string"
}

Delete an IP address or CIDR block from the Access List

Delete an IP address or CIDR block from the Access List of your App Services app

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

ipId
required
string

The IP address entry denoted by ip_id with the information given in the request body

Responses

List VPC Private Endpoints

Get a list of all private endpoints configured for the App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a VPC Private Endpoint

Configure a new private endpoint for the App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
_id
string
cloud_provider_region
string

The cloud provider region that hosts the private endpoint.

cloud_provider_endpoint_id
string

The private endpoint ID from the cloud provider.

comment
string

An optional comment that describes the endpoint.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "cloud_provider_region": "aws-us-east-1",
  • "cloud_provider_endpoint_id": "vpce-12345678",
  • "comment": "string"
}

Get a VPC Private Endpoint

Get a specific private endpoint configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

privateEndpointId
required
string

The _id ObjectID of a VPC private endpoint.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "cloud_provider_region": "aws-us-east-1",
  • "cloud_provider_endpoint_id": "vpce-12345678",
  • "comment": "string"
}

Modify a VPC Private Endpoint

Update the configuration of a private endpoint.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

privateEndpointId
required
string

The _id ObjectID of a VPC private endpoint.

Request Body schema: application/json
_id
string
cloud_provider_region
string

The cloud provider region that hosts the private endpoint.

cloud_provider_endpoint_id
string

The private endpoint ID from the cloud provider.

comment
string

An optional comment that describes the endpoint.

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "cloud_provider_region": "aws-us-east-1",
  • "cloud_provider_endpoint_id": "vpce-12345678",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "cloud_provider_region": "aws-us-east-1",
  • "cloud_provider_endpoint_id": "vpce-12345678",
  • "comment": "string"
}

Delete a VPC Private Endpoint

Delete a private endpoint.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

privateEndpointId
required
string

The _id ObjectID of a VPC private endpoint.

Responses

List VPC Private Endpoint Services

Get a list of all private endpoint services configured for the App.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Toggle Non-VPC Requests

For Apps with Private Endpoints enabled, toggle whether or not the App processes requests that originate from outside of the VPC.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
allow_non_vpc_client_requests
boolean

Set to true to allow non-VPC requests. Set to false to restrict non-VPC requests.

Responses

Request samples

Content type
application/json
{
  • "allow_non_vpc_client_requests": true
}

Get User Refresh Token Expiration Time

Get the current expiration time in seconds for user session refresh tokens.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
{
  • "expiration_time_seconds": 5184000
}

Set User Refresh Token Expiration Time

Set the expiration time in seconds for user session refresh tokens.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
expiration_time_seconds
number [ 1800 .. 15552000 ]
Default: 5184000

The time in seconds that a user session refresh token is valid for after it is issued. After this time, the token is expired and the user must re-authenticate.

The expiration time must be between 30 minutes and 5 years, inclusive. The default expiration time is 60 days.

Responses

Request samples

Content type
application/json
{
  • "expiration_time_seconds": 5184000
}

Data Sources & Services

View and manage your application's data sources and third-party services [Deprecated]

Link multiple data sources

Call this endpoint to link multiple data sources to an App. The total limit of linked data sources per App is 100. Data Sources linked by this endpoint will have ReadAndWrite default rules.

Authorizations:
tokenAuth
Request Body schema: application/json
Array
name
string

Create a name to identify each cluster you want to link.

type
string
Enum: "mongodb-atlas" "datalake"

The type of the data source you want to link.

object (LinkingDataSourceConfig)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "failedClusterNames": [
    ]
}

List all data sources and third-party services

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a data source or third-party service

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json
One of
name
string

The service name.

type
string

The type of service.

object (AtlasClusterServiceConfigInstance)

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "string",
  • "config": {
    }
}

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "name": "string",
  • "type": "string",
  • "config": {
    }
}

Get a data source or third-party service

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "name": "string",
  • "type": "string",
  • "config": {
    }
}

Delete a data source or third-party service

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Update a service

Update a service.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Run a command associated with a service

Run a command associated with a service.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

commandName
required
string

Command name

Responses

Get information about the underlying Atlas mongod

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "gitVersion": "string",
  • "versionArray": [
    ],
  • "javascriptEngine": "string",
  • "bits": "string",
  • "debug": true,
  • "maxBsonObjectSize": 0
}

Get a Service Configuration

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update a Service Configuration

Update a Data Source or Third-Party Service [Deprecated] configuration.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json
One of
clusterName
required
string

The cluster name of the data source within. The name may be at most 64 characters long and must only contain ASCII letters, numbers, underscores, and hyphens.

readPreference
required
string
Enum: "primary" "primaryPreferred" "secondary" "secondaryPreferred" "nearest"

The read preference mode for read requests to the data source.

readPreferenceTagSets
Array of strings (ReadPreferencesTagSet)
Items Enum: "server1" "server2"

Target read operations to specific members of a replica set.

wireProtocolEnabled
required
clusterId
number

The service ID.

groupName
string

The name of the group that contains the service.

orgName
string

The name of the organization that contains the service.

Responses

Request samples

Content type
application/json
Example
{
  • "clusterName": "Cluster0",
  • "readPreference": "primary",
  • "readPreferenceTagSets": [
    ],
  • "wireProtocolEnabled": true,
  • "clusterId": "05e821b3975d271289f372e3a",
  • "groupName": "Project 0",
  • "orgName": "MongoDB_Org"
}

Generate a JSON schema from sample

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

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json
database_name
required
string

The name of the database that contains the collection.

collection_name
required
string

The name of the collection to sample and generate a schema for.

limit
required
integer

The maximum number of documents to include in the sample.

Responses

Request samples

Content type
application/json
{
  • "database_name": "string",
  • "collection_name": "string",
  • "limit": 0
}

Response samples

Content type
application/json
{
  • "schema": { }
}

Sync

Get information about sync for your application.

Get Flexible Sync information

Retrieve sync data for a specific Atlas App Services App when using Flexible Sync.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
{
  • "clusterId": "string",
  • "clusterName": "string",
  • "clusterType": "atlas",
  • "flexible_sync": {
    },
  • "groupName": "string",
  • "orgName": "string",
  • "readPreference": "primary",
  • "wireProtocolEnabled": true
}

Get Partition-Based Sync information

Retrieve partition field data when using Partition-Based Sync.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
service_id
required
string

The Service ID for the linked cluster.

Responses

Response samples

Content type
application/json
{
  • "service_id": "string",
  • "partition_fields": [
    ]
}

Triggers

View and manage your application's triggers.

Get all triggers

Get a list of all triggers in your application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a trigger

Create a new trigger in your application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

A configuration for a database, scheduled, or authentication trigger.

One of
name
required
string

The trigger's name.

type
required
string
Value: "DATABASE"

The trigger type. For database triggers, this value is always "DATABASE".

disabled
boolean
Default: false

If true, the trigger is disabled and does not listen for events or execute.

required
object

An object that defines configuration values for the trigger.

function_id
string

The ID of the function that the trigger calls when it fires.

This value is the same as event_processors.FUNCTION.function_id. You can either define the value here or in event_processors.FUNCTION.function_id. The App Services backend duplicates the value to the configuration location where you did not define it.

For example, if you define function_id, the backend duplicates it to event_processors.FUNCTION.function_id.

function_name
string

The name of the function that the trigger calls when it fires, i.e. the function described by function_id.

This value is the same as event_processors.FUNCTION.function_name. You can either define the value here or in event_processors.FUNCTION.function_name. The App Services backend duplicates the value to the configuration location where you did not define it.

For example, if you define function_name, the backend duplicates it to event_processors.FUNCTION.function_name.

object

An object where each field name is an event processor ID and each value is an object that configures its corresponding event processor. For an example configuration object, see Send Trigger Events to AWS EventBridge.

object

An object that defines custom error handling for an AWS EventBridge trigger. Valid only for "DATABASE" type triggers with "AWS_EVENTBRIDGE" event processors.

_id
string

The trigger's unique ID.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "onNewEmployee",
  • "type": "DATABASE",
  • "function_id": "5eea9ca4ca0e356e2c2a148a",
  • "config": {
    }
}

Response samples

Content type
application/json
Example
{
  • "name": "onNewEmployee",
  • "type": "DATABASE",
  • "function_id": "5eea9ca4ca0e356e2c2a148a",
  • "config": {
    }
}

Get a trigger

Get the configuration for an existing trigger in your application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

triggerId
required
string

The unique _id value of a trigger.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "onNewEmployee",
  • "type": "DATABASE",
  • "function_id": "5eea9ca4ca0e356e2c2a148a",
  • "config": {
    }
}

Update a trigger

Modify an existing trigger in your application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

triggerId
required
string

The unique _id value of a trigger.

Request Body schema: application/json

The updated trigger configuration.

One of
name
required
string

The trigger's name.

type
required
string
Value: "DATABASE"

The trigger type. For database triggers, this value is always "DATABASE".

disabled
boolean
Default: false

If true, the trigger is disabled and does not listen for events or execute.

required
object

An object that defines configuration values for the trigger.

function_id
string

The ID of the function that the trigger calls when it fires.

This value is the same as event_processors.FUNCTION.function_id. You can either define the value here or in event_processors.FUNCTION.function_id. The App Services backend duplicates the value to the configuration location where you did not define it.

For example, if you define function_id, the backend duplicates it to event_processors.FUNCTION.function_id.

function_name
string

The name of the function that the trigger calls when it fires, i.e. the function described by function_id.

This value is the same as event_processors.FUNCTION.function_name. You can either define the value here or in event_processors.FUNCTION.function_name. The App Services backend duplicates the value to the configuration location where you did not define it.

For example, if you define function_name, the backend duplicates it to event_processors.FUNCTION.function_name.

object

An object where each field name is an event processor ID and each value is an object that configures its corresponding event processor. For an example configuration object, see Send Trigger Events to AWS EventBridge.

object

An object that defines custom error handling for an AWS EventBridge trigger. Valid only for "DATABASE" type triggers with "AWS_EVENTBRIDGE" event processors.

_id
string

The trigger's unique ID.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "onNewEmployee",
  • "type": "DATABASE",
  • "function_id": "5eea9ca4ca0e356e2c2a148a",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "error_code": "string"
}

Delete a trigger

Remove an existing trigger from your application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

triggerId
required
string

The unique _id value of a trigger.

Responses

Response samples

Content type
application/json
{ }

Resume a suspended trigger

Resume a suspended database trigger.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

triggerId
required
string

The unique _id value of a trigger.

Request Body schema: application/json

Configuration options for the resume operation.

disable_token
boolean

If true, resumes the trigger without processing missed events. Otherwise, attempts to resume the trigger from the first change event after it failed by using a resume token.

Responses

Request samples

Content type
application/json
{
  • "disable_token": true
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Users

View and manage your application's users.

List users

List confirmed user accounts.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
after
string

The id of the last user returned by a previous paginated request.

sort
string

The field name to sort results by. The only valid value is the default: _id.

desc
boolean

If true, returns sorted results in descending order. If not specified or set to false, results return in ascending order.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a user

Create a new email/password user account.

Note: You cannot create user accounts through the Admin API for any authentication provider other than email/password.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The user to create

email
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "identities": [
    ],
  • "type": "normal",
  • "creation_date": 0,
  • "last_authentication_date": 0,
  • "disabled": true,
  • "data": { }
}

Verify & decode an access token

Verify a that a user's client access token is valid.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The user's client access token. The access token represents a logged in application user. This is not the same as the access_token that you use to work with the Admin API.

token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
Example
"token expired"

Get a User

Get a specific user account by ID.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "identities": [
    ],
  • "type": "normal",
  • "creation_date": 0,
  • "last_authentication_date": 0,
  • "disabled": true,
  • "data": { }
}

Delete a user

Delete a specific user account by ID.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

Change a user's email

Change the email address for an email/password user by ID.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Request Body schema: application/json

The new email address for the user.

email
required
string

The new email for the user.

Responses

Request samples

Content type
application/json
{
  • "email": "new_email@example.com"
}

List a user's devices

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

Response samples

Content type
application/json
[
  • { }
]

Revoke user sessions

Revoke all of a user's sessions.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

Enable a user

Enable a user.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

Disable a user

Disable a user.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

userId
required
string

User Account ID

Responses

List pending users

List pending user account registrations. Returns up to 50 pending users in a call.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
after
string

The unique _id for a pending user. List pending users can return 50 pending users at a time. To view additional results, find the _id of the last pending user listed in the previous call to list pending users. Call list pending users again, passing the _id to the after parameter.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Delete a pending email/password authentication user

Delete a pending user.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

email
required
string

Email address

Responses

User Confirmation

Confirm pending users with the built-in email confirmation flow.

Send a confirmation email

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

email
required
string

Email address

Responses

Confirm a pending user

Confirm a pending user.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

email
required
string

Email address

Responses

Rerun a user confirmation workflow

Reruns a pending user's confirmation workflow.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

email
required
string

Email address

Responses

Values

View and manage your application's values.

List all values defined in an application.

List all values defined in an application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Define a Value in an application

Define a Value in an application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The value to create.

name
required
string
private
required
boolean
value
required
any (AnyValue)

Any valid JSON value

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "private": true,
  • "value": null
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "private": true,
  • "value": null
}

Retrieve a value definition from an application

Retrieve a value definition from an application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

valueId
required
string

The unique _id value of a value.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "private": true,
  • "from_secret": true,
  • "value": null
}

Delete a value defined in an application.

Delete a value defined in an application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

valueId
required
string

The unique _id value of a value.

Responses

Update a value definition in an application

Update a value definition in an application.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

valueId
required
string

The unique _id value of a value.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

[Deprecated] Push Notifications

View and manage your application's push notifications.

List push notifications

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

query Parameters
state
string (MessageState)
Enum: "sent" "draft"

Only list notifications with the given state.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a push notification

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

Request Body schema: application/json

The notification to create.

label
required
string
message
required
string
topic
required
string
state
required
string (MessageState)
Enum: "sent" "draft"

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "message": "string",
  • "topic": "string",
  • "state": "sent"
}

Retrieve a push notification message

Retrieve a push notification message.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

messageId
required
string

Message ID

Responses

Response samples

Content type
application/json
{
  • "allowed_ips": "string",
  • "appID": "string",
  • "label": "string",
  • "message": "string",
  • "topic": "string",
  • "created": "string",
  • "sent": "string",
  • "state": "sent"
}

Delete a push notification message

Delete a push notification message.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

messageId
required
string

Message ID

Responses

Update a push notification

Update a push notification message.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

messageId
required
string

Message ID

Responses

Response samples

Content type
application/json
{
  • "allowed_ips": "string",
  • "appID": "string",
  • "label": "string",
  • "message": "string",
  • "topic": "string",
  • "created": "string",
  • "sent": "string",
  • "state": "sent"
}

Set a push notification's type

Set a push notification's type.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

messageId
required
string

Message ID

Responses

Send a push notification

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

messageId
required
string

Message ID

Responses

[Deprecated] Webhooks

View and manage your application's webhooks.

List webhooks

List webhooks.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "function_source": "string",
  • "respond_result": true,
  • "options": {
    }
}

Create a webhook

Create a webhook.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

Request Body schema: application/json

The webhook to create.

name
required
string
function_source
required
string
respond_result
required
boolean
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "function_source": "string",
  • "respond_result": true,
  • "options": {
    }
}

Retrieve a webhook

Retrieve a webhook.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

incomingWebhookId
required
string

The unique _id value of an incoming webhook

Responses

Delete a webhook

Delete a webhook.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

incomingWebhookId
required
string

The unique _id value of an incoming webhook

Responses

Update a webhook

Update a webhook.

Authorizations:
tokenAuth
path Parameters
groupId
required
string

An Atlas Project/Group ID.

appId
required
string

The ObjectID of your application. The App Services API Project and Application IDs section demonstrates how to find this value.

serviceId
required
string

The unique _id value of a service.

incomingWebhookId
required
string

The unique _id value of an incoming webhook

Request Body schema: application/json

The updated state of the webhook.

name
required
string
function_source
required
string
respond_result
required
boolean
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "function_source": "string",
  • "respond_result": true,
  • "options": {
    }
}