MongoDB Root API

openapi: 3.0.1
info:
  description: "The MongoDB Atlas Administration API allows developers to manage all components in MongoDB Atlas.\n\nThe Atlas Administration API supports OAuth2 Service Accounts and HTTP Digest-based API keys. Service accounts are the recommended authentication method and API keys are considered a legacy option.\n\nTo authenticate with a Service Account, first exchange its client ID and secret for an access token using the OAuth 2.0 Client Credentials flow. Atlas provides a token endpoint at `POST https://cloud.mongodb.com/api/oauth/token`, which returns a Bearer token that is reusable and valid for 1 hour (3600 seconds).\n\nFor example, to [return a list of your organizations](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listorgs) with [cURL](https://en.wikipedia.org/wiki/CURL), first generate an access token and then use that token to call the same Atlas Administration API endpoint shown in the current example:\n\n```\nACCESS_TOKEN=$(curl -fsS --request POST https://cloud.mongodb.com/api/oauth/token \\\n  --header \"Authorization: Basic $(printf '%s' \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64 | tr -d '\\n')\" \\\n  --header \"Content-Type: application/x-www-form-urlencoded\" \\\n  --header \"Accept: application/json\" \\\n  --data \"grant_type=client_credentials\" | jq -r '.access_token')\n\ncurl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/orgs?pretty=true\"\n```\n\nIf your organization requires an IP access list for the Atlas Administration API, the token can be created from any IP address, but the API call that uses the token must originate from an allowed IP.\n\nTo learn more, see [Get Started with the Atlas Administration API](https://www.mongodb.com/docs/atlas/configure-api-access/). For support, see [MongoDB Support](https://www.mongodb.com/support/get-started).\n\nYou can also explore the various endpoints available through the Atlas Administration API in MongoDB's [Postman workspace](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/) (requires a Postman account)."
  license:
    name: CC BY-NC-SA 3.0 US
    url: https://creativecommons.org/licenses/by-nc-sa/3.0/us/
  termsOfService: https://www.mongodb.com/mongodb-management-service-terms-and-conditions
  title: MongoDB Atlas Administration Access Tracking Root API
  version: '2.0'
  x-xgen-sha: 3d70e065843c008b9871ea7836c98c9de6f202f9
servers:
- url: https://cloud.mongodb.com
security:
- ServiceAccounts: []
- DigestAuth: []
tags:
- description: Returns details that describe the MongoDB Cloud build and the access token that requests this resource. This starts the MongoDB Cloud API.
  name: Root
paths:
  /api/atlas/v2:
    get:
      description: This resource returns information about the MongoDB application along with API key meta data.
      operationId: getSystemStatus
      parameters:
      - $ref: '#/components/parameters/envelope'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          content:
            application/vnd.atlas.2023-01-01+json:
              schema:
                $ref: '#/components/schemas/SystemStatus'
              x-xgen-version: '2023-01-01'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/HeaderRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/HeaderRateLimitRemaining'
        '401':
          description: Unauthorized.
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServerError'
      summary: Return the Status of This MongoDB Application
      tags:
      - Root
      x-codeSamples:
      - lang: cURL
        label: Atlas CLI
        source: atlas api root getSystemStatus --help
      - lang: go
        label: Go
        source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.GetSystemStatusApiParams{}\n\tsdkResp, httpResp, err := client.RootApi.\n\t\tGetSystemStatusWithParams(ctx, params).\n\t\tExecute()\n}\n"
      - lang: cURL
        label: curl (Service Accounts)
        source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2?pretty=true\""
      - lang: cURL
        label: curl (Digest)
        source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n  --digest --include \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2?pretty=true\""
      x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Root/operation/getSystemStatus
      x-xgen-method-verb-override:
        customMethod: false
        verb: getSystemStatus
  /api/atlas/v2/unauth/controlPlaneIPAddresses:
    get:
      description: Returns all control plane IP addresses.
      operationId: listControlPlaneIpAddresses
      parameters:
      - $ref: '#/components/parameters/envelope'
      responses:
        '200':
          content:
            application/vnd.atlas.2023-11-15+json:
              schema:
                $ref: '#/components/schemas/ControlPlaneIPAddresses'
              x-xgen-version: '2023-11-15'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/HeaderRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/HeaderRateLimitRemaining'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServerError'
      security: []
      summary: Return All Control Plane IP Addresses
      tags:
      - Root
      x-codeSamples:
      - lang: cURL
        label: Atlas CLI
        source: atlas api root listControlPlaneAddresses --help
      - lang: go
        label: Go
        source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.ListControlPlaneIpAddressesApiParams{}\n\tsdkResp, httpResp, err := client.RootApi.\n\t\tListControlPlaneIpAddressesWithParams(ctx, params).\n\t\tExecute()\n}\n"
      - lang: cURL
        label: curl (Service Accounts)
        source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/unauth/controlPlaneIPAddresses?pretty=true\""
      - lang: cURL
        label: curl (Digest)
        source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n  --digest --include \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/unauth/controlPlaneIPAddresses?pretty=true\""
      x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Root/operation/listControlPlaneIpAddresses
      x-xgen-operation-id-override: listControlPlaneAddresses
components:
  responses:
    internalServerError:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 500
            errorCode: UNEXPECTED_ERROR
            reason: Internal Server Error
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Internal Server Error.
    forbidden:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 403
            errorCode: CANNOT_CHANGE_GROUP_NAME
            reason: Forbidden
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Forbidden.
    tooManyRequests:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 429
            errorCode: RATE_LIMITED
            reason: Too Many Requests
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Too Many Requests.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/HeaderRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/HeaderRateLimitRemaining'
        Retry-After:
          $ref: '#/components/headers/HeaderRetryAfter'
  schemas:
    Link:
      properties:
        href:
          description: Uniform Resource Locator (URL) that points another API resource to which this response has some relationship. This URL often begins with `https://cloud.mongodb.com/api/atlas`.
          example: https://cloud.mongodb.com/api/atlas
          type: string
        rel:
          description: Uniform Resource Locator (URL) that defines the semantic relationship between this resource and another API resource. This URL often begins with `https://cloud.mongodb.com/api/atlas`.
          example: self
          type: string
      type: object
    OutboundControlPlaneCloudProviderIPAddresses:
      description: List of outbound IP addresses from the Atlas control plane, categorized by cloud provider. If your network allows inbound HTTP requests only from specific IP addresses, you must allow access from the following IP addresses so that Atlas can communicate with your webhooks and KMS.
      properties:
        aws:
          additionalProperties:
            description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
            items:
              description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
          readOnly: true
          type: object
        azure:
          additionalProperties:
            description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
            items:
              description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
          readOnly: true
          type: object
        gcp:
          additionalProperties:
            description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
            items:
              description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
          readOnly: true
          type: object
      readOnly: true
      title: Outbound Control Plane IP Addresses By Cloud Provider
      type: object
    ApiError:
      properties:
        badRequestDetail:
          $ref: '#/components/schemas/BadRequestDetail'
        detail:
          description: Describes the specific conditions or reasons that cause each type of error.
          type: string
        error:
          description: HTTP status code returned with this error.
          externalDocs:
            url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
          format: int32
          readOnly: true
          type: integer
        errorCode:
          description: Application error code returned with this error.
          readOnly: true
          type: string
        parameters:
          description: Parameters used to give more information about the error.
          items:
            type: object
          readOnly: true
          type: array
        reason:
          description: Application error message returned with this error.
          readOnly: true
          type: string
      required:
      - error
      - errorCode
      type: object
    AccessListItemView:
      properties:
        cidrBlock:
          description: Range of IP addresses in Classless Inter-Domain Routing (CIDR) notation that found in this project's access list.
          pattern: ^((([0-9]{1,3}\.){3}[0-9]{1,3})|(:{0,2}([0-9a-f]{1,4}:){0,7}[0-9a-f]{1,4}[:]{0,2}))((%2[fF]|/)[0-9]{1,3})+$
          readOnly: true
          type: string
        ipAddress:
          description: IP address included in the API access list.
          pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$
          readOnly: true
          type: string
      required:
      - ipAddress
      type: object
    ControlPlaneIPAddresses:
      description: List of IP addresses in the Atlas control plane.
      properties:
        inbound:
          $ref: '#/components/schemas/InboundControlPlaneCloudProviderIPAddresses'
        outbound:
          $ref: '#/components/schemas/OutboundControlPlaneCloudProviderIPAddresses'
      title: Control Plane IP Addresses
      type: object
    BadRequestDetail:
      description: Bad request detail.
      properties:
        fields:
          description: Describes all violations in a client request.
          items:
            $ref: '#/components/schemas/FieldViolation'
          type: array
      readOnly: true
      type: object
    SystemStatus:
      properties:
        apiKey:
          $ref: '#/components/schemas/ApiKey'
        appName:
          description: Human-readable label that identifies the service from which you requested this response.
          enum:
          - MongoDB Atlas
          readOnly: true
          type: string
        build:
          description: Unique 40-hexadecimal digit hash that identifies the latest git commit merged for this application.
          example: 83be55e140f493c88e7f578aae96548dd881587b
          readOnly: true
          type: string
        links:
          description: List of one or more Uniform Resource Locators (URLs) that point to API sub-resources, related API resources, or both. RFC 5988 outlines these relationships.
          externalDocs:
            description: Web Linking Specification (RFC 5988)
            url: https://datatracker.ietf.org/doc/html/rfc5988
          items:
            $ref: '#/components/schemas/Link'
          readOnly: true
          type: array
        throttling:
          description: Flag that indicates whether someone enabled throttling on this service.
          readOnly: true
          type: boolean
      required:
      - apiKey
      - appName
      - build
      - throttling
      type: object
    CloudAccessRoleAssignment:
      description: MongoDB Cloud user's roles and the corresponding organization or project to which that role applies. Each role can apply to one organization or one project but not both.
      properties:
        groupId:
          description: Unique 24-hexadecimal digit string that identifies the project to which this role belongs. You can set a value for this parameter or `orgId` but not both in the same request.
          example: 32b6e34b3d91647abb20e7b8
          maxLength: 24
          minLength: 24
          pattern: ^([a-f0-9]{24})$
          type: string
        orgId:
          description: Unique 24-hexadecimal digit string that identifies the organization to which this role belongs. You can set a value for this parameter or `groupId` but not both in the same request.
          example: 32b6e34b3d91647abb20e7b8
          maxLength: 24
          minLength: 24
          pattern: ^([a-f0-9]{24})$
          type: string
        roleName:
          description: Human-readable label that identifies the collection of privileges that MongoDB Cloud grants a specific API key, MongoDB Cloud user, or MongoDB Cloud team. These roles include organization- and project-level roles.
          externalDocs:
            description: MongoDB Cloud User Roles
            url: https://www.mongodb.com/docs/atlas/reference/user-roles/
          type: string
      title: Role Assignment
      type: object
    ApiKey:
      description: Details contained in one API key.
      nullable: true
      properties:
        accessList:
          description: List of network addresses granted access to this API using this API key.
          items:
            $ref: '#/components/schemas/AccessListItemView'
          readOnly: true
          type: array
        id:
          description: Unique 24-hexadecimal digit string that identifies this organization API key.
          example: 32b6e34b3d91647abb20e7b8
          pattern: ^([a-f0-9]{24})$
          readOnly: true
          type: string
        publicKey:
          description: Public API key value set for the specified organization API key.
          maxLength: 8
          minLength: 8
          readOnly: true
          type: string
        roles:
          description: List that contains roles that the API key needs to have. All roles you provide must be valid for the specified project or organization. Each request must include a minimum of one valid role. The resource returns all project and organization roles assigned to the Cloud user.
          items:
            $ref: '#/components/schemas/CloudAccessRoleAssignment'
          readOnly: true
          type: array
      readOnly: true
      required:
      - accessList
      - id
      - publicKey
      - roles
      type: object
    FieldViolation:
      properties:
        description:
          description: A description of why the request element is bad.
          type: string
        field:
          description: A path that leads to a field in the request body.
          type: string
      required:
      - description
      - field
      type: object
    InboundControlPlaneCloudProviderIPAddresses:
      description: List of inbound IP addresses to the Atlas control plane, categorized by cloud provider. If your application allows outbound HTTP requests only to specific IP addresses, you must allow access to the following IP addresses so that your API requests can reach the Atlas control plane.
      properties:
        aws:
          additionalProperties:
            description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
            items:
              description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in AWS. Each key identifies an Amazon Web Services (AWS) region. Each value identifies control plane IP addresses in the AWS region.
          readOnly: true
          type: object
        azure:
          additionalProperties:
            description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
            items:
              description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in Azure. Each key identifies an Azure region. Each value identifies control plane IP addresses in the Azure region.
          readOnly: true
          type: object
        gcp:
          additionalProperties:
            description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
            items:
              description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
              readOnly: true
              type: string
            readOnly: true
            type: array
          description: Control plane IP addresses in GCP. Each key identifies a Google Cloud (GCP) region. Each value identifies control plane IP addresses in the GCP region.
          readOnly: true
          type: object
      readOnly: true
      title: Inbound Control Plane IP Addresses By Cloud Provider
      type: object
  parameters:
    envelope:
      description: Flag that indicates whether Application wraps the response in an `envelope` JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.
      in: query
      name: envelope
      schema:
        default: false
        type: boolean
    pretty:
      description: Flag that indicates whether the response body should be in the prettyprint format.
      in: query
      name: pretty
      schema:
        default: false
        externalDocs:
          description: Prettyprint
          url: https://en.wikipedia.org/wiki/Prettyprint
        type: boolean
  headers:
    HeaderRetryAfter:
      description: The minimum time you should wait, in seconds, before retrying the API request. This header might be returned for 429 or 503 error responses.
      schema:
        type: integer
    HeaderRateLimitLimit:
      description: The maximum number of requests that a user can make within a specific time window.
      schema:
        type: integer
    HeaderRateLimitRemaining:
      description: The number of requests remaining in the current rate limit window before the limit is reached.
      schema:
        type: integer
  securitySchemes:
    DigestAuth:
      scheme: digest
      type: http
    ServiceAccounts:
      description: Learn more about [Service Accounts](https://www.mongodb.com/docs/atlas/api/service-accounts-overview).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://cloud.mongodb.com/api/oauth/token
      type: oauth2
x-externalLinks:
- label: Back to Atlas Docs
  url: https://www.mongodb.com/docs/atlas/
- label: API Changelog
  url: https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/
x-topics:
- content: The MongoDB Atlas Administration API is rate limited. To learn more about rate limiting, see the [Atlas Documentation on Rate Limiting](http://dochub.mongodb.org/core/atlas-api-rate-limit)
  title: Rate Limiting