Microsoft Dynamics NAV Environments API

openapi: 3.1.0
info:
  title: Business Central Administration Center Accounts Environments API
  description: REST API for programmatic administration of Dynamics 365 Business Central environments. Enables querying and managing production and sandbox environments, setting up administrative notifications, viewing tenant telemetry, managing apps, scheduling updates, and performing environment operations such as copy, rename, restore, and delete.
  version: '2.28'
  contact:
    name: Microsoft Dynamics Support
    email: bcsupport@microsoft.com
    url: https://dynamics.microsoft.com/support/
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  termsOfService: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
- url: https://api.businesscentral.dynamics.com/admin/v2.28
  description: Business Central Administration Center
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Environments
  description: Manage Business Central environments
paths:
  /applications/environments:
    get:
      summary: List All Environments
      description: Returns a list of all environments across all application families for the tenant.
      operationId: listAllEnvironments
      tags:
      - Environments
      responses:
        '200':
          description: Successfully retrieved environments
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Environment'
              examples:
                Listallenvironments200Example:
                  summary: Default listAllEnvironments 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - friendlyName: example_value
                      type: Production
                      name: Example Title
                      countryCode: example_value
                      applicationFamily: example_value
                      aadTenantId: '500123'
                      status: NotReady
                      webClientLoginUrl: https://www.example.com
                      webServiceUrl: https://www.example.com
                      locationName: example_value
                      geoName: example_value
                      ringName: example_value
                      appInsightsKey: example_value
                      softDeletedOn: '2026-01-15T10:30:00Z'
                      hardDeletePendingOn: '2026-01-15T10:30:00Z'
                      deleteReason: example_value
                      appSourceAppsUpdateCadence: example_value
                      versionDetails:
                        version: example_value
                        gracePeriodStartDate: '2026-01-15T10:30:00Z'
                        enforcedUpdatePeriodStartDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments:
    get:
      summary: List Environments by Application Family
      description: Returns a list of environments for the specified application family.
      operationId: listEnvironments
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      responses:
        '200':
          description: Successfully retrieved environments
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Environment'
              examples:
                Listenvironments200Example:
                  summary: Default listEnvironments 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - friendlyName: example_value
                      type: Production
                      name: Example Title
                      countryCode: example_value
                      applicationFamily: example_value
                      aadTenantId: '500123'
                      status: NotReady
                      webClientLoginUrl: https://www.example.com
                      webServiceUrl: https://www.example.com
                      locationName: example_value
                      geoName: example_value
                      ringName: example_value
                      appInsightsKey: example_value
                      softDeletedOn: '2026-01-15T10:30:00Z'
                      hardDeletePendingOn: '2026-01-15T10:30:00Z'
                      deleteReason: example_value
                      appSourceAppsUpdateCadence: example_value
                      versionDetails:
                        version: example_value
                        gracePeriodStartDate: '2026-01-15T10:30:00Z'
                        enforcedUpdatePeriodStartDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Application family not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Listenvironments404Example:
                  summary: Default listEnvironments 404 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}:
    get:
      summary: Get an Environment
      description: Returns the properties for the specified environment.
      operationId: getEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      responses:
        '200':
          description: Successfully retrieved environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
              examples:
                Getenvironment200Example:
                  summary: Default getEnvironment 200 response
                  x-microcks-default: true
                  value:
                    friendlyName: example_value
                    type: Production
                    name: Example Title
                    countryCode: example_value
                    applicationFamily: example_value
                    aadTenantId: '500123'
                    status: NotReady
                    webClientLoginUrl: https://www.example.com
                    webServiceUrl: https://www.example.com
                    locationName: example_value
                    geoName: example_value
                    ringName: example_value
                    appInsightsKey: example_value
                    softDeletedOn: '2026-01-15T10:30:00Z'
                    hardDeletePendingOn: '2026-01-15T10:30:00Z'
                    deleteReason: example_value
                    appSourceAppsUpdateCadence: example_value
                    versionDetails:
                      version: example_value
                      gracePeriodStartDate: '2026-01-15T10:30:00Z'
                      enforcedUpdatePeriodStartDate: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Environment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Getenvironment404Example:
                  summary: Default getEnvironment 404 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      summary: Create a New Environment
      description: Creates a new environment with sample data. The operation is asynchronous; poll the environment operations endpoint to track status.
      operationId: createEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnvironmentRequest'
            examples:
              CreateenvironmentRequestExample:
                summary: Default createEnvironment request
                x-microcks-default: true
                value:
                  environmentType: Production
                  countryCode: example_value
                  ringName: example_value
                  applicationVersion: example_value
      responses:
        '201':
          description: Environment creation initiated (API v2.8 and earlier)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
              examples:
                Createenvironment201Example:
                  summary: Default createEnvironment 201 response
                  x-microcks-default: true
                  value:
                    friendlyName: example_value
                    type: Production
                    name: Example Title
                    countryCode: example_value
                    applicationFamily: example_value
                    aadTenantId: '500123'
                    status: NotReady
                    webClientLoginUrl: https://www.example.com
                    webServiceUrl: https://www.example.com
                    locationName: example_value
                    geoName: example_value
                    ringName: example_value
                    appInsightsKey: example_value
                    softDeletedOn: '2026-01-15T10:30:00Z'
                    hardDeletePendingOn: '2026-01-15T10:30:00Z'
                    deleteReason: example_value
                    appSourceAppsUpdateCadence: example_value
                    versionDetails:
                      version: example_value
                      gracePeriodStartDate: '2026-01-15T10:30:00Z'
                      enforcedUpdatePeriodStartDate: '2026-01-15T10:30:00Z'
        '202':
          description: Environment creation scheduled (API v2.9 and later)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Createenvironment202Example:
                  summary: Default createEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Createenvironment400Example:
                  summary: Default createEnvironment 400 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Environment already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Createenvironment409Example:
                  summary: Default createEnvironment 409 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Delete an Environment
      description: Soft deletes the specified environment. The environment is retained for 14 days during which it can be recovered. Environments with status Creating Failed or Removing Failed are permanently deleted immediately.
      operationId: deleteEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      responses:
        '202':
          description: Delete operation scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Deleteenvironment202Example:
                  summary: Default deleteEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Environment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Deleteenvironment404Example:
                  summary: Default deleteEnvironment 404 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}/copy:
    post:
      summary: Copy an Environment
      description: Creates a new environment as a copy of an existing environment's data.
      operationId: copyEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CopyEnvironmentRequest'
            examples:
              CopyenvironmentRequestExample:
                summary: Default copyEnvironment request
                x-microcks-default: true
                value:
                  environmentName: example_value
                  type: Production
      responses:
        '201':
          description: Copy initiated (API v2.8 and earlier)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
              examples:
                Copyenvironment201Example:
                  summary: Default copyEnvironment 201 response
                  x-microcks-default: true
                  value:
                    friendlyName: example_value
                    type: Production
                    name: Example Title
                    countryCode: example_value
                    applicationFamily: example_value
                    aadTenantId: '500123'
                    status: NotReady
                    webClientLoginUrl: https://www.example.com
                    webServiceUrl: https://www.example.com
                    locationName: example_value
                    geoName: example_value
                    ringName: example_value
                    appInsightsKey: example_value
                    softDeletedOn: '2026-01-15T10:30:00Z'
                    hardDeletePendingOn: '2026-01-15T10:30:00Z'
                    deleteReason: example_value
                    appSourceAppsUpdateCadence: example_value
                    versionDetails:
                      version: example_value
                      gracePeriodStartDate: '2026-01-15T10:30:00Z'
                      enforcedUpdatePeriodStartDate: '2026-01-15T10:30:00Z'
        '202':
          description: Copy operation scheduled (API v2.9 and later)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Copyenvironment202Example:
                  summary: Default copyEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Copyenvironment400Example:
                  summary: Default copyEnvironment 400 response
                  x-microcks-default: true
                  value:
                    code: example_value
                    message: example_value
                    target: example_value
                    extensionData: example_value
                    clientError:
                    - code: example_value
                      message: example_value
                      target: example_value
                      extensionData: example_value
                      clientError: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}/rename:
    post:
      summary: Rename an Environment
      description: Schedules a rename operation on an environment.
      operationId: renameEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - NewEnvironmentName
              properties:
                NewEnvironmentName:
                  type: string
                  description: The new name for the environment
            examples:
              RenameenvironmentRequestExample:
                summary: Default renameEnvironment request
                x-microcks-default: true
                value:
                  NewEnvironmentName: example_value
      responses:
        '202':
          description: Rename operation scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Renameenvironment202Example:
                  summary: Default renameEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}/restore:
    post:
      summary: Restore an Environment
      description: Restores an existing environment from a point in time in the past.
      operationId: restoreEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreEnvironmentRequest'
            examples:
              RestoreenvironmentRequestExample:
                summary: Default restoreEnvironment request
                x-microcks-default: true
                value:
                  EnvironmentName: example_value
                  EnvironmentType: Production
                  PointInTime: '2026-01-15T10:30:00Z'
                  SkipInstallingPTEs: true
                  SkipInstallingThirdPartyGlobalApps: true
                  SkipEnvironmentCleanup: true
      responses:
        '202':
          description: Restore operation scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Restoreenvironment202Example:
                  summary: Default restoreEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}/recover:
    post:
      summary: Recover a Deleted Environment
      description: Recovers a soft-deleted environment.
      operationId: recoverEnvironment
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      responses:
        '202':
          description: Recovery operation scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentOperation'
              examples:
                Recoverenvironment202Example:
                  summary: Default recoverEnvironment 202 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    type: create
                    status: Queued
                    aadTenantId: '500123'
                    createdOn: '2026-01-15T10:30:00Z'
                    startedOn: '2026-01-15T10:30:00Z'
                    completedOn: '2026-01-15T10:30:00Z'
                    createdBy: example_value
                    errorMessage: example_value
                    parameters: example_value
                    environmentName: example_value
                    environmentType: example_value
                    productFamily: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{applicationFamily}/environments/{environmentName}/availableRestorePeriods:
    get:
      summary: Get Available Restore Periods
      description: Returns an ordered list of available restore periods for the environment.
      operationId: getAvailableRestorePeriods
      tags:
      - Environments
      parameters:
      - $ref: '#/components/parameters/applicationFamily'
      - $ref: '#/components/parameters/environmentName'
      responses:
        '200':
          description: Successfully retrieved restore periods
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/RestorePeriod'
              examples:
                Getavailablerestoreperiods200Example:
                  summary: Default getAvailableRestorePeriods 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - from: '2026-01-15T10:30:00Z'
                      to: '2026-01-15T10:30:00Z'
                      correspondingApplicationPackageVersion: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RestorePeriod:
      type: object
      properties:
        from:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        to:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        correspondingApplicationPackageVersion:
          type: string
          example: example_value
    EnvironmentOperation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Operation ID used for tracking
          example: abc123
        type:
          type: string
          description: Type of operation
          enum:
          - create
          - copy
          - delete
          - softDelete
          - recover
          - environmentRename
          - pitRestore
          - environmentAppInstall
          - environmentAppUninstall
          - environmentAppUpdate
          - environmentAppHotfix
          - modify
          - update
          - restart
          - moveToAnotherAadTenant
          example: create
        status:
          type: string
          description: Status of the operation
          enum:
          - Queued
          - Scheduled
          - Running
          - Succeeded
          - Failed
          - Canceled
          - Skipped
          example: Queued
        aadTenantId:
          type: string
          format: uuid
          description: Microsoft Entra tenant ID
          example: '500123'
        createdOn:
          type: string
          format: date-time
          description: When the operation was created
          example: '2026-01-15T10:30:00Z'
        startedOn:
          type: string
          format: date-time
          description: When the operation started executing
          example: '2026-01-15T10:30:00Z'
        completedOn:
          type: string
          format: date-time
          description: When the operation completed
          example: '2026-01-15T10:30:00Z'
        createdBy:
          type: string
          description: Who created the operation
          example: example_value
        errorMessage:
          type: string
          description: Error message for failed operations
          example: example_value
        parameters:
          type: object
          description: Operation-specific parameters
          additionalProperties: true
          example: example_value
        environmentName:
          type: string
          description: Name of the affected environment
          example: example_value
        environmentType:
          type: string
          description: Type of the affected environment
          example: example_value
        productFamily:
          type: string
          description: Product family of the affected environment
          example: example_value
    Environment:
      type: object
      properties:
        friendlyName:
          type: string
          description: Display name of the environment
          example: example_value
        type:
          type: string
          description: Environment type
          enum:
          - Production
          - Sandbox
          example: Production
        name:
          type: string
          description: Environment name, unique within an application family
          example: Example Title
        countryCode:
          type: string
          description: Country/region code where the environment is deployed
          example: example_value
        applicationFamily:
          type: string
          description: Family of the environment application
          example: example_value
        aadTenantId:
          type: string
          format: uuid
          description: Microsoft Entra tenant ID that owns the environment
          example: '500123'
        status:
          type: string
          description: Current status of the environment
          enum:
          - NotReady
          - Removing
          - Preparing
          - Active
          - Upgrading
          - CreatingFailed
          - RemovingFailed
          - SoftDeleting
          - SoftDeletingFailed
          - SoftDeleted
          - Recovering
          - RecoveringFailed
          example: NotReady
        webClientLoginUrl:
          type: string
          format: uri
          description: URL to log into the environment
          example: 

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/navision/refs/heads/main/openapi/navision-environments-api-openapi.yml