{"title":"App Management API","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/appmanagement/app-management-api/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/appmanagement/app-management-api, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/appmanagement/app-management-api","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn about managing Embed apps by using the App Management API.","date":"2021-04-01","meta":{"topic":"article"},"outline":[{"level":2,"title":"Entities","slug":"entities","at":54,"chars":12},{"level":2,"title":"App","slug":"app","at":66,"chars":1867},{"level":3,"title":"Description","slug":"description","at":73,"chars":451},{"level":3,"title":"Properties","slug":"properties","at":524,"chars":536},{"level":3,"title":"Available Endpoints","slug":"available-endpoints","at":1060,"chars":24},{"level":3,"title":"List apps","slug":"list-apps","at":1084,"chars":849},{"level":4,"title":"Parameters","slug":"parameters","at":1281,"chars":109},{"level":4,"title":"Example Request","slug":"example-request","at":1390,"chars":126},{"level":4,"title":"Example Response","slug":"example-response","at":1516,"chars":417},{"level":2,"title":"Country","slug":"country","at":1933,"chars":2586},{"level":3,"title":"Properties","slug":"properties-1","at":2186,"chars":202},{"level":3,"title":"Available Endpoints","slug":"available-endpoints-1","at":2388,"chars":24},{"level":3,"title":"List countries/regions","slug":"list-countriesregions","at":2412,"chars":724},{"level":4,"title":"Parameters","slug":"parameters-1","at":2595,"chars":123},{"level":4,"title":"Example Request","slug":"example-request-1","at":2718,"chars":132},{"level":4,"title":"Example Response","slug":"example-response-1","at":2850,"chars":286},{"level":3,"title":"Get country","slug":"get-country","at":3136,"chars":629},{"level":4,"title":"Parameters","slug":"parameters-2","at":3319,"chars":196},{"level":4,"title":"Example Request","slug":"example-request-2","at":3515,"chars":135},{"level":4,"title":"Example Response","slug":"example-response-2","at":3650,"chars":115},{"level":3,"title":"Add or update country","slug":"add-or-update-country","at":3765,"chars":754},{"level":4,"title":"Parameters","slug":"parameters-3","at":3957,"chars":281},{"level":4,"title":"Example Request","slug":"example-request-3","at":4238,"chars":166},{"level":4,"title":"Example Response","slug":"example-response-3","at":4404,"chars":115},{"level":2,"title":"Principal","slug":"principal","at":4519,"chars":4545},{"level":3,"title":"Description","slug":"description-1","at":4532,"chars":545},{"level":3,"title":"Properties","slug":"properties-2","at":5077,"chars":391},{"level":3,"title":"Available Endpoints","slug":"available-endpoints-2","at":5468,"chars":24},{"level":3,"title":"List principals","slug":"list-principals","at":5492,"chars":915},{"level":4,"title":"Parameters","slug":"parameters-4","at":5696,"chars":180},{"level":4,"title":"Example Request","slug":"example-request-4","at":5876,"chars":177},{"level":4,"title":"Example Response","slug":"example-response-4","at":6053,"chars":354},{"level":3,"title":"Get principal by ID","slug":"get-principal-by-id","at":6407,"chars":768},{"level":4,"title":"Parameters","slug":"parameters-5","at":6582,"chars":166},{"level":4,"title":"Example Request","slug":"example-request-5","at":6748,"chars":170},{"level":4,"title":"Example Response","slug":"example-response-5","at":6918,"chars":257},{"level":3,"title":"Remove principal","slug":"remove-principal","at":7175,"chars":593},{"level":4,"title":"Parameters","slug":"parameters-6","at":7429,"chars":166},{"level":4,"title":"Example Request","slug":"example-request-6","at":7595,"chars":173},{"level":3,"title":"Add or update principal","slug":"add-or-update-principal","at":7768,"chars":1296},{"level":4,"title":"Parameters","slug":"parameters-7","at":8165,"chars":257},{"level":4,"title":"Example Request","slug":"example-request-7","at":8422,"chars":384},{"level":4,"title":"Example Response","slug":"example-response-6","at":8806,"chars":258},{"level":2,"title":"Version","slug":"version","at":9064,"chars":9397},{"level":3,"title":"Description","slug":"description-2","at":9075,"chars":241},{"level":3,"title":"Properties","slug":"properties-3","at":9316,"chars":1417},{"level":4,"title":"Version","slug":"version-1","at":9331,"chars":954},{"level":4,"title":"Dependency","slug":"dependency","at":10285,"chars":448},{"level":3,"title":"List versions","slug":"list-versions","at":10733,"chars":1609},{"level":4,"title":"Parameters","slug":"parameters-8","at":10930,"chars":252},{"level":4,"title":"Example Request","slug":"example-request-8","at":11182,"chars":193},{"level":4,"title":"Example Response","slug":"example-response-7","at":11375,"chars":967},{"level":3,"title":"Upload version","slug":"upload-version","at":12342,"chars":1964},{"level":4,"title":"Parameters","slug":"parameters-9","at":12872,"chars":190},{"level":4,"title":"Upload version request","slug":"upload-version-request","at":13062,"chars":274},{"level":4,"title":"Example Request","slug":"example-request-9","at":13336,"chars":222},{"level":4,"title":"Example Response","slug":"example-response-8","at":13558,"chars":748},{"level":3,"title":"Download version","slug":"download-version","at":14306,"chars":794},{"level":4,"title":"Parameters","slug":"parameters-10","at":14547,"chars":314},{"level":4,"title":"Example Request","slug":"example-request-10","at":14861,"chars":239},{"level":3,"title":"Get version","slug":"get-version","at":15100,"chars":1266},{"level":4,"title":"Parameters","slug":"parameters-11","at":15288,"chars":177},{"level":4,"title":"Example Request","slug":"example-request-11","at":15465,"chars":153},{"level":4,"title":"Example Response","slug":"example-response-9","at":15618,"chars":748},{"level":3,"title":"Update version","slug":"update-version","at":16366,"chars":2095},{"level":4,"title":"Parameters","slug":"parameters-12","at":16636,"chars":291},{"level":4,"title":"Example Request","slug":"example-request-12","at":16927,"chars":231},{"level":4,"title":"Example Request","slug":"example-request-13","at":17158,"chars":552},{"level":4,"title":"Example Response","slug":"example-response-10","at":17710,"chars":751},{"level":2,"title":"Environment","slug":"environment","at":18461,"chars":1636},{"level":3,"title":"Description","slug":"description-3","at":18476,"chars":101},{"level":3,"title":"Properties","slug":"properties-4","at":18577,"chars":493},{"level":3,"title":"List environments","slug":"list-environments","at":19070,"chars":1027},{"level":4,"title":"Parameters","slug":"parameters-13","at":19286,"chars":195},{"level":4,"title":"Example Request","slug":"example-request-14","at":19481,"chars":178},{"level":4,"title":"Example Response","slug":"example-response-11","at":19659,"chars":438},{"level":2,"title":"Environment Hotfix","slug":"environment-hotfix","at":20097,"chars":7320},{"level":3,"title":"Description","slug":"description-4","at":20119,"chars":588},{"level":3,"title":"Properties","slug":"properties-5","at":20707,"chars":1250},{"level":3,"title":"List environment hotfixes","slug":"list-environment-hotfixes","at":21957,"chars":1340},{"level":4,"title":"Parameters","slug":"parameters-14","at":22210,"chars":195},{"level":4,"title":"Example Request","slug":"example-request-15","at":22405,"chars":194},{"level":4,"title":"Example Response","slug":"example-response-12","at":22599,"chars":698},{"level":3,"title":"Get environment hotfix","slug":"get-environment-hotfix","at":23297,"chars":1209},{"level":4,"title":"Parameters","slug":"parameters-15","at":23570,"chars":183},{"level":4,"title":"Example Request","slug":"example-request-16","at":23753,"chars":192},{"level":4,"title":"Example Response","slug":"example-response-13","at":23945,"chars":561},{"level":3,"title":"Schedule environment hotfix","slug":"schedule-environment-hotfix","at":24506,"chars":1562},{"level":4,"title":"Parameters","slug":"parameters-16","at":24857,"chars":206},{"level":4,"title":"Example Request","slug":"example-request-17","at":25063,"chars":444},{"level":4,"title":"Example Response","slug":"example-response-14","at":25507,"chars":561},{"level":3,"title":"Update environment hotfix","slug":"update-environment-hotfix","at":26068,"chars":1349},{"level":4,"title":"Parameters","slug":"parameters-17","at":26365,"chars":267},{"level":4,"title":"Example Request","slug":"example-request-18","at":26632,"chars":225},{"level":4,"title":"Example Response","slug":"example-response-15","at":26857,"chars":560},{"level":2,"title":"Getting detailed error messages","slug":"getting-detailed-error-messages","at":27417,"chars":753},{"level":2,"title":"Related information","slug":"related-information","at":28170,"chars":71}],"text":"> INTRODUCED IN: Business Central 2020 release wave 1\n## Entities\n## App\n### Description\nThe app entity represents a Business Central App that has been registered with the service and so it can be managed via the API. The app entity contains some basic metadata about the app, such as:\n its ID\n the Microsoft Entra tenant ID of the publisher's organization\n which Azure location the respective .app files and other metadata should be stored in.\n> NOTE\n> An app doesn't refer to any specific .app file or version of the app.\n### Properties\nName|Description|Schema\nID|The ID of the app. The ID must remain the same across all app versions.|string (uuid)\npublisher|The publisher's name.|string\npublisherAadTenantId|The ID of the Microsoft Entra tenant that represents the publisher's organization.|string (uuid)\npublisherContactEmail|The publisher's contact e-mail address.|string\nstorageLocation|The Azure location in which data related to this app should be stored.|string\n_etag|The entity tag that contains a value unique to the entity's current state.|string\n### Available Endpoints\n### List apps\nLists all apps that match the provided (optional) filter that the current principal can access.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps?$filter=<odata_filter>\n```\n#### Parameters\nType|Name|Description|Schema\nquery|$filter|Restricts the set of items returned.|OData filter\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps?$filter=storageLocation eq 'West Europe'\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"id\": \"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\",\n            \"publisher\": \"Contoso\",\n            \"publisherAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n            \"publisherContactEmail\": \"publisher@contoso.com\",\n            \"storageLocation\": \"West Europe\",\n            \"_etag\": \"5c47bfb0-d80c-4780-99ed-c3a3d38ac539\"\n        }\n    ]\n}\n```\n## Country\nThe country entity represents a country that an app is available in.\nA country is represented by its ISO 3166-1 alpha-2 (2-letter) country code.\nSpecific versions of Business Central Apps can be made available for specific countries/regions.\n### Properties\nName|Description|Schema\ncountryCode|The ISO 3166-1 alpha-2 (2-letter) code for the country.|string\n_etag|The entity tag that contains a value unique to the entity's current state.|string\n### Available Endpoints\n### List countries/regions\nLists all countries/regions the specified app has been made available in.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app to list the countries/regions for.|string (uuid)\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"countryCode\": \"US\",\n            \"_etag\": \"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1\"\n        },\n        {\n            \"countryCode\": \"DK\",\n            \"_etag\": \"b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2\"\n        }\n    ]\n}\n```\n### Get country\nGets the country with the specified country code in the specified app.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the country belongs to.|string (uuid)\npath|countryCode|The ISO 3166-1 alpha-2 (2-letter) code of the country.|string\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US\n```\n#### Example Response\n```json\n{\n    \"countryCode\": \"US\",\n    \"_etag\": \"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1\"\n}\n```\n### Add or update country\nAdds a new country to the specified app or updates an existing one.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the country belongs to.|string (uuid)\npath|countryCode|The ISO 3166-1 alpha-2 (2-letter) code of the country to add.|string\nbody|country|The country properties that should be added or updated.|#country\n#### Example Request\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/AT\n\n{\n    \"countryCode\": \"AT\"\n}\n```\n#### Example Response\n```json\n{\n    \"countryCode\": \"AT\",\n    \"_etag\": \"cccccccc-dddd-eeee-3333-444444444444\"\n}\n```\n## Principal\n### Description\nThe principal entity represents a Microsoft Entra ID user or application that has some level of access to an app.\nPrincipal can have different roles that determine which actions they're allowed to do.\nThe currently supported roles are:\n Owner - Owners are allowed to do all available actions on all entities.\n Contributor - Contributors have similar permissions to owners, except that they aren't allowed to add/update principals.\n Reader - Readers can read information about the various entities, but can't add/update anything.\n### Properties\nName|Description|Schema\naadTenantId|The ID of the Microsoft Entra tenant the principal belongs to.|string (uuid)\nid|The ID of Microsoft Entra ID user/application.|string (uuid)\nroles|The list of roles the principal has assigned.|string[]\ntype|The principal type.|enum (User, Application)\n_etag|The entity tag that contains a value unique to the entity's current state.|string\n### Available Endpoints\n### List principals\nLists all principals that match the provided filter within the specified app.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/principals?$filter=<odata_filter>\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app to list the principals for.|string (uuid)\nquery|$filter|Restricts the set of items returned.|OData filter\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/principals?$filter=type eq 'User' and 'Owner' in roles\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"id\": \"cccccccc-dddd-eeee-3333-444444444444\",\n            \"type\": \"User\",\n            \"aadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n            \"roles\": [\n                \"Owner\"\n            ],\n            \"_etag\": \"c99541ab-a0d2-4807-86f8-e1eb1853eb4f\"\n        }\n    ]\n}\n```\n### Get principal by ID\nGets the principal with the specified ID in the specified app.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/principals/{id}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the principal belongs to.|string (uuid)\npath|id|The ID of the principal.|string (uuid)\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/principals/cccccccc-dddd-eeee-3333-444444444444\n```\n#### Example Response\n```json\n{\n    \"id\": \"cccccccc-dddd-eeee-3333-444444444444\",\n    \"type\": \"User\",\n    \"aadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"roles\": [\n        \"Owner\"\n    ],\n    \"_etag\": \"c99541ab-a0d2-4807-86f8-e1eb1853eb4f\"\n}\n```\n### Remove principal\nRemoves the principal with the specified ID in the specified app.\nNote: Only principals with the Owner role are allowed to remove principals.\n```\nDELETE https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/principals/{id}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the principal belongs to.|string (uuid)\npath|id|The ID of the principal.|string (uuid)\n#### Example Request\n```\nDELETE https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/principals/cccccccc-dddd-eeee-3333-444444444444\n```\n### Add or update principal\nAdds or updates the specified principal that belongs to the specified app.\nNote: Only principals with the Owner role are allowed to add or update principals.\nNote: The aadTenantId field should only be specified in the request body when the principal being added is of type User.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/principals/{id}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the principal belongs to.|string (uuid)\npath|id|The ID of the principal to add or update.|string (uuid)\nbody|principal|The properties that should be added or updated.|#principal\n#### Example Request\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/principals/cccccccc-dddd-eeee-3333-444444444444\n\n{\n    \"aadTenantId\":  \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"Type\":  \"User\",\n    \"roles\":  [\n                  \"Reader\"\n              ]\n}\n```\nWhen using `Type:\"Application\"`, the aadTenantId must not be used.\n#### Example Response\n```json\n{\n    \"id\": \"cccccccc-dddd-eeee-3333-444444444444\",\n    \"type\": \"User\",\n    \"aadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"roles\": [\n        \"Reader\"\n    ],\n    \"_etag\": \"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1\"\n}\n```\n## Version\n### Description\nA version represents an .app file that has been uploaded for a specific country in an app.\nIf a version of an app should be available in multiple countries, then the .app file needs to be uploaded to each country separately.\n### Properties\n#### Version\nName|Description|Schema\nappId|The ID of the app.|string (uuid)\navailability|The version's availability.|enum (Preview, Available, Deprecated)\nbuildVersion|The build number of the version.|integer (int32)\ncountryCode|The country that the version was uploaded for.|string\ndependencies|The dependencies of the uploaded package.|#dependency[]\nmajorVersion|The major number of the version.|integer (int32)\nminorVersion|The minor number of the version.|integer (int32)\nname|The name of the app.|string\npackageId|The ID of the uploaded package.|string (uuid)\npublisher|The publisher of the app.|string\nrevisionVersion|The revision number of the version.|integer (int32)\nstatus|The version's status.|enum (Uploading, Uploaded, UploadFailed)\nuploadedOn|The UTC date and time the version was uploaded on.|string (date-time)\nversion|The version of the app.|string\n_etag|The entity tag that contains a value unique to the entity's current state.|string\n#### Dependency\nName|Description|Schema\nappId|The dependency app ID.|string (uuid)\nname|The dependency app name.|string\npublisher|The dependency app publisher.|string\nversion|The minimum version of the dependency.|string\nincompatibleFromVersion|The initial app version of the dependency that is no longer compatible with the dependent app. If this value is set then it means that versions greater or equal to it are considered incompatible.|string\n### List versions\nLists all versions that match the provided filter.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/versions?$filter=<odata_filter>\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app to list the versions for.|string (uuid)\npath|countryCode|The code of the country to list the versions for.|string\nquery|$filter|Restricts the set of items returned.|OData filter\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions?$filter=MajorVersion eq 16 and MinorVersion eq 0\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"version\": \"16.0.1.2\",\n            \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n            \"countryCode\": \"US\",\n            \"packageId\": \"ffffffff-5555-6666-7777-aaaaaaaaaaaa\",\n            \"publisher\": \"Example Publisher\",\n            \"name\": \"ExampleApp\",\n            \"uploadedOn\": \"2019-07-09T11:54:45.5414576Z\",\n            \"availability\": \"Available\",\n            \"status\": \"Uploaded\",\n            \"dependencies\": [\n                {\n                    \"appId\": \"44445555-eeee-6666-ffff-7777aaaa8888\",\n                    \"name\": \"Example Dependency\",\n                    \"publisher\": \"Other Publisher\",\n                    \"version\": \"1.0.0.0\"\n                }\n            ],\n            \"majorVersion\": 16,\n            \"minorVersion\": 0,\n            \"buildVersion\": 1,\n            \"revisionVersion\": 2,\n            \"_etag\": \"c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3\"\n        }\n    ]\n}\n```\n### Upload version\nUploads an .app file into the specified app and country based on the provided package contents.\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/versions\n```\n> IMPORTANT\n> Make sure that you registered your app with the service and added a country to it, before you attempt to upload the app version.\n> NOTE\n> If you want to update an app to a version that introduces breaking changes, see Upgrading an App by Using ForceSync<app-management-updating-with-forcesync>.\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\nbody|requestData|The request data.|#upload-version-request\n#### Upload version request\nName|Description|Schema\ninitialAvailability|The initial availability that the uploaded app version should have.|enum (Preview, Available, Deprecated)\npackageContents|The base64-encoded contents of the package (.app file) to upload.|string (byte)\n#### Example Request\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions\n\n{\n    \"initialAvailability\": \"Preview\",\n    \"packageContents\": <contents>\n}\n```\n#### Example Response\n```json\n{\n    \"version\": \"16.0.1.2\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"packageId\": \"ffffffff-5555-6666-7777-aaaaaaaaaaaa\",\n    \"publisher\": \"Example Publisher\",\n    \"name\": \"ExampleApp\",\n    \"uploadedOn\": \"2019-07-09T11:54:45.5414576Z\",\n    \"availability\": \"Preview\",\n    \"status\": \"Uploaded\",\n    \"dependencies\": [\n        {\n            \"appId\": \"44445555-eeee-6666-ffff-7777aaaa8888\",\n            \"name\": \"Example Dependency\",\n            \"publisher\": \"Other Publisher\",\n            \"version\": \"1.0.0.0\"\n        }\n    ],\n    \"majorVersion\": 16,\n    \"minorVersion\": 0,\n    \"buildVersion\": 1,\n    \"revisionVersion\": 2,\n    \"_etag\": \"c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3\"\n}\n```\n### Download version\nDownloads the .app file linked to the specified version.\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/versions/{versionNumber}/getPackageContents -OutFile {saveToFile}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the version belongs to.|string (uuid)\npath|countryCode|The country code.|string\npath|versionNumber|The version number of the version to update.|string\npath|saveToFile|The path and the name you want to use for file you download.|string\n#### Example Request\nDownloads an app file.\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions/16.0.1.2/getPackageContents -OutFile \"C:\\temp\\ExampleApp-16.0.1.2.app\"\n```\n### Get version\nGets the version in the specified app and country.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/versions/{versionNumber}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\npath|versionNumber|The version number.|string\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions/16.0.1.2\n```\n#### Example Response\n```json\n{\n    \"version\": \"16.0.1.2\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"packageId\": \"ffffffff-5555-6666-7777-aaaaaaaaaaaa\",\n    \"publisher\": \"Example Publisher\",\n    \"name\": \"ExampleApp\",\n    \"uploadedOn\": \"2019-07-09T11:54:45.5414576Z\",\n    \"availability\": \"Preview\",\n    \"status\": \"Uploaded\",\n    \"dependencies\": [\n        {\n            \"appId\": \"44445555-eeee-6666-ffff-7777aaaa8888\",\n            \"name\": \"Example Dependency\",\n            \"publisher\": \"Other Publisher\",\n            \"version\": \"1.0.0.0\"\n        }\n    ],\n    \"majorVersion\": 16,\n    \"minorVersion\": 0,\n    \"buildVersion\": 1,\n    \"revisionVersion\": 2,\n    \"_etag\": \"c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3\"\n}\n```\n### Update version\nUpdates the version in the specified app and country with the provided updated data.\nNote: only some properties can be updated.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/versions/{versionNumber}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app that the version belongs to.|string (uuid)\npath|countryCode|The country code.|string\npath|versionNumber|The version number of the version to update.|string\nbody|version|The properties that should be updated.|#version\n#### Example Request\nMarking an app version as deprecated.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions/16.0.1.2\n\n{\n    \"availability\": \"Deprecated\"\n}\n```\n#### Example Request\nMarks older versions of your app as incompatible with a dependency app, starting with a specific version. In such cases, make sure you upload another version of your app that is compatible with the new version of the dependency app.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/versions/16.0.1.2\n\n{\n    \"dependencies\": [\n        {\n            \"appId\": \"63ca2fa4-4f03-4f2b-a480-172fef340d3f\",\n            \"incompatibleFromVersion\": \"16.0.0.0\"\n        }\n    ]\n}\n```\n#### Example Response\n```json\n{\n    \"version\": \"16.0.1.2\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"packageId\": \"ffffffff-5555-6666-7777-aaaaaaaaaaaa\",\n    \"publisher\": \"Example Publisher\",\n    \"name\": \"ExampleApp\",\n    \"uploadedOn\": \"2019-07-09T11:54:45.5414576Z\",\n    \"availability\": \"Deprecated\",\n    \"status\": \"Uploaded\",\n    \"dependencies\": [\n        {\n            \"appId\": \"44445555-eeee-6666-ffff-7777aaaa8888\",\n            \"name\": \"Example Dependency\",\n            \"publisher\": \"Other Publisher\",\n            \"version\": \"1.0.0.0\"\n        }\n    ],\n    \"majorVersion\": 16,\n    \"minorVersion\": 0,\n    \"buildVersion\": 1,\n    \"revisionVersion\": 2,\n    \"_etag\": \"c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3\"\n}\n```\n## Environment\n### Description\nRepresents a customer's environment that has a specific version of an app installed.\n### Properties\nName|Description|Schema\naadTenantId|The ID of the customer's Microsoft Entra tenant.|string (uuid)\nappId|The ID of the installed app.|string (uuid)\napplicationFamily|The environment's application family.|string\ncountryCode|The country code the environment belongs to.|string\nlocationName|The Azure location the environment is in.|string\nname|The environment's name.|string\ntype|The environment's type.|enum (Production, Sandbox)\nversion|The version of the installed app.|string\n### List environments\nLists the environments in the specified app and country that have the app installed.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/environments\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\nquery|$filter|Restricts the set of items returned.|OData filter\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/environments?$filter=version eq '16.0.1.2'\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"aadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n            \"version\": \"16.0.1.2\",\n            \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n            \"countryCode\": \"US\",\n            \"applicationFamily\": \"Business Central\",\n            \"locationName\": \"West Europe\",\n            \"name\": \"MyCustomer\",\n            \"type\": \"Production\"\n        }\n    ]\n}\n```\n## Environment Hotfix\n### Description\nAn `environment hotfix` represents the action of pushing out an update (new version) of an app to a customer's environment as part of fixing a critical issue.\nOnly versions where the major and minor components haven't changed can be pushed as hotfixes.\nIt is also not possible to apply a hotfix to an already installed application version of preview availability. To apply a hotfix, you need to either uninstall the preview application version from the environment you are trying to update or change the availability of that application version from preview to available.\n### Properties\nName|Description|Schema\nappId|The ID of the app.|string (uuid)\ncompletedOn|Date and time (UTC) when the hotfix was applied.|string (date-time)\ncountryCode|The country code.|string\ncreatedOn|Date and time (UTC) when the hotfix request was created.|string (date-time)\nenvironmentAadTenantId|The ID of the customer's Microsoft Entra tenant.|string (uuid)\nenvironmentApplicationFamily|The environment's application family.|string\nenvironmentName|The environment's name.|string\nerrorMessage|The error message provided when the hotfix was unable to be applied.|string\nid|The ID hotfix request.|string (uuid)\nignoreUpgradeWindow|Determines whether the environment's upgrade window should be ignored when applying the hotfix.|boolean\nrunAfter|Date and time (UTC) after which hotfix should start to be applied.|string (date-time)\nsourceAppVersion|The version of the app that was installed before the hotfix was applied.|string\nstartedOn|Date and time (UTC) when the hotfix started to be applied.|string (date-time)\nstatus|Status.|enum (Scheduled, Running, Succeeded, Failed, Canceled, Skipped)\ntargetAppVersion|The version of the app containing the fixes that should be applied. The value is the version that the app will be updated to.|string\n### List environment hotfixes\nLists all the hotfix operations that were requested for a specific app and country.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/environmentHotfixes?$filter=<odata_filter>\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\nquery|$filter|Restricts the set of items returned.|OData filter\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/environmentHotfixes?$filter=targetAppVersion eq '16.0.1.2'\n```\n#### Example Response\n```json\n{\n    \"value\": [\n        {\n            \"id\": \"dddddddd-3333-4444-5555-eeeeeeeeeeee\",\n            \"environmentAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n            \"sourceAppVersion\": \"16.0.0.5\",\n            \"targetAppVersion\": \"16.0.1.2\",\n            \"status\": \"Scheduled\",\n            \"createdOn\": \"2020-03-05T15:41:20.6468128Z\",\n            \"runAfter\": \"2020-03-05T17:30:00.0000000Z\",\n            \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n            \"countryCode\": \"US\",\n            \"environmentApplicationFamily\": \"Business Central\",\n            \"environmentName\": \"MyCustomer\",\n            \"environmentType\": \"Production\"\n        }\n    ]\n}\n```\n### Get environment hotfix\nGets an `environment hotfix` operation by its ID.\nThis endpoint can be used to track the status/outcome of a hotfix request.\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/environmentHotfixes/{id}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\npath|id|The ID of the hotfix request.|string (uuid)\n#### Example Request\n```\nGET https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/environmentHotfixes/dddddddd-3333-4444-5555-eeeeeeeeeeee\n```\n#### Example Response\n```json\n{\n    \"id\": \"dddddddd-3333-4444-5555-eeeeeeeeeeee\",\n    \"environmentAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"sourceAppVersion\": \"16.0.0.5\",\n    \"targetAppVersion\": \"16.0.1.2\",\n    \"status\": \"Scheduled\",\n    \"createdOn\": \"2020-03-05T15:41:20.6468128Z\",\n    \"runAfter\": \"2020-03-05T17:30:00.0000000Z\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"environmentApplicationFamily\": \"Business Central\",\n    \"environmentName\": \"MyCustomer\",\n    \"environmentType\": \"Production\"\n}\n```\n### Schedule environment hotfix\nSchedules a hotfix for a specific environment to the specified version.\nThe hotfix operation ID that is returned can be used to track the status/outcome of the operation (see: #get-environment-hotfix).\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/environmentHotfixes\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\nbody|environmentHotfix|Environment hotfix to schedule.|#environment-hotfix\n#### Example Request\n```\nPOST https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/environmentHotfixes\n\n{\n    \"environmentAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"targetAppVersion\": \"16.0.1.2\",\n    \"runAfter\": \"2020-03-05T17:30:00.0000000Z\",\n    \"environmentApplicationFamily\": \"Business Central\",\n    \"environmentName\": \"MyCustomer\",\n    \"environmentType\": \"Production\"\n}\n```\n#### Example Response\n```json\n{\n    \"id\": \"dddddddd-3333-4444-5555-eeeeeeeeeeee\",\n    \"environmentAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"sourceAppVersion\": \"16.0.0.5\",\n    \"targetAppVersion\": \"16.0.1.2\",\n    \"status\": \"Scheduled\",\n    \"createdOn\": \"2020-03-05T15:41:20.6468128Z\",\n    \"runAfter\": \"2020-03-05T17:30:00.0000000Z\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"environmentApplicationFamily\": \"Business Central\",\n    \"environmentName\": \"MyCustomer\",\n    \"environmentType\": \"Production\"\n}\n```\n### Update environment hotfix\nUpdates an existing `environment hotfix` operation.\nIt can currently only be used to cancel a requested hotfix that hasn't yet started running.\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/{appId}/countries/{countryCode}/environmentHotfixes/{id}\n```\n#### Parameters\nType|Name|Description|Schema\npath|appId|The ID of the app.|string (uuid)\npath|countryCode|The country code.|string\npath|id|The ID of the hotfix request.|string (uuid)\nbody|environmentHotfix|Environment hotfix properties to update.|#environment-hotfix\n#### Example Request\n```\nPATCH https://apps.businesscentral.dynamics.com/v1.4/apps/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb/countries/US/environmentHotfixes/dddddddd-3333-4444-5555-eeeeeeeeeeee\n\n{\n    \"status\": \"Canceled\"\n}\n\n```\n#### Example Response\n```json\n{\n    \"id\": \"dddddddd-3333-4444-5555-eeeeeeeeeeee\",\n    \"environmentAadTenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"sourceAppVersion\": \"16.0.0.5\",\n    \"targetAppVersion\": \"16.0.1.2\",\n    \"status\": \"Canceled\",\n    \"createdOn\": \"2020-03-05T15:41:20.6468128Z\",\n    \"runAfter\": \"2020-03-05T17:30:00.0000000Z\",\n    \"appId\": \"00001111-aaaa-2222-bbbb-3333cccc4444\",\n    \"countryCode\": \"US\",\n    \"environmentApplicationFamily\": \"Business Central\",\n    \"environmentName\": \"MyCustomer\",\n    \"environmentType\": \"Production\"\n}\n```\n## Getting detailed error messages\nTo get detailed error messages from the API calls, wrap the calls in a try-catch block, as shown in the following PowerShell example:\n```powershell\ntry {\n    Invoke-WebRequest ....\n}\ncatch [System.Net.WebException]\n{\n    $Exception = $_.Exception\n    $respStream = $Exception.Response.GetResponseStream()\n    $reader = New-Object System.IO.StreamReader($respStream)\n    $respBody = $reader.ReadToEnd() | ConvertFrom-Json | ConvertTo-Json -Depth 100\n    $reader.Close();\n    Write-Error $Exception.Response.Headers[\"ms-correlation-x\"]\n    Write-Error $Exception.Message\n    Write-Error $respBody -ErrorAction Stop\n}\n```\nPlease make sure you provide full output in textual format when reporting the issues to Microsoft.\n## Related information\nApp Management for ISVs<app-management-overview>"}