The Deploy API only works for apps that are deployed to Mendix Cloud.
1 Introduction
The Deploy API allows you to manage application environments in Mendix Cloud. You can retrieve the status of, and start and stop, applications. You can also configure new model versions and deploy them to application environments. To create and manage deployment packages, you also need the Build API. For backup-related actions, refer to the Backups API.
The v1 Deploy API only supports the endpoints listed here. For all other deployment API calls, use the v2 API or v4 API.
Mendix recommends using calls from the same version of the API where possible. This is because the naming varies across versions. For example, the {appId} in the version 4 API is retrieved as the {ProjectId} from the version 1 API.
You can use webhooks to trigger CI/CD pipelines that use this API. These are described in Webhooks.
This image provides a domain model representation of the concepts discussed below and how these are related:
2 Authentication
The Deploy API requires authentication via API keys that are bound to your Mendix account.
Because APIs are designed for automated systems, the Deploy API does not require two-factor authentication, which is normally required to make changes to production environments. This is a potential security risk. Therefore, the Technical Contact of an application needs to allow API access explicitly for team members who want to use the Deploy API. This can be configured from the Node Security screen under App Settings. By default, API access is already enabled for test and acceptance environments for all team members. To perform an action via the Deploy API, such as transporting a new deployment package, both the Transport and API Access permissions need to be enabled.
3 API Calls
Only Retrieve apps, Create Free App environment, and Retrieve app API calls are supported for Free Apps. Please note that most API calls—with the exception of Upload Package—require that the Content-Type header be set to application/json.
3.1 Retrieve Apps
3.1.1 Description
Retrieves all apps to which the authenticated user has access as a regular user that have environments created on Mendix Cloud. This includes all licensed apps and any Free Apps that have been deployed.
This API call does not return the same results as you can see within the Developer Portal. It includes all licensed and free apps on Mendix Cloud. Free apps include all apps that have been created or edited in Studio Pro, even if they have then been deployed to a different cloud, such as Mendix for Private Cloud.
In the Developer Portal:
The Nodes screen in the Developer Portal shows all the licensed apps which are returned by this request, but does not show any Free Apps.
The My Apps screen shows both licensed apps and Free Apps, but also includes apps that are deployed to other platforms (such as Mendix for Private Cloud or SAP BTP) and Free Apps that have not yet been deployed and therefore have no environments set up for them.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps
3.1.2 Request
Example Request
1
2
3
4
5
GET /api/1/apps
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.1.3 Output
List of objects with the following key-value pairs:
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps
3.2.2 Request
Request Parameter
An object with the following key-value pair:
ProjectId (String) : The Developer Portal project identifier that should be linked to the new Free App. This value can be found on the General tab of the Settings page of your app, and it is represented as App ID.
Retrieves a specific app to which the authenticated user has access as a regular user. This app can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>
3.3.2 Request
3.3.2.1 Request Parameter
AppId (String): Sub-domain name of an app.
3.3.2.2 Example Request
1
2
3
4
5
GET /api/1/apps/calc
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
Retrieves all environments that are connected to a specific app to which the authenticated user has access as a regular user. These environments can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments
3.4.2 Request
3.4.2.1 Request Parameter
AppId (String): Subdomain name of an app.
3.4.2.2 Example Request
1
2
3
4
5
6
GET /api/1/apps/calc/environments
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.4.3 Output
List of objects with the following key-value pairs:
Status (String): Status of the environment. Possible values: Empty, Stopped, Running.
EnvironmentId (String): Unique identifier of the environment.
Url (String): URL to access your application.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production or the name of a flexible environment.
ModelVersion (String): The version number of the package deployed in your environment.
MendixVersion (String): The Mendix version number of the package deployed in your environment.
Production (Boolean): A flag indicating if this environment is a production environment.
Retrieves a specific environment that is connected to a specific app to which the authenticated user has access as a regular user. These environments can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>
3.5.2 Request
3.5.2.1 Request Parameters
AppId (String): Subdomain name of an app.
Mode (String): The mode of the environment of the app. An environment with this mode should exist.
3.5.2.2 Example Request
1
2
3
4
5
GET /api/1/apps/calc/environments/Acceptance
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.5.3 Output
An object with the following key-value pairs:
Status (String): Status of the environment. Possible values: Empty, Stopped, Running.
EnvironmentId (String): Unique identifier of the environment.
Url (String): URL to access your application.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production or the name of a flexible environment.
ModelVersion (String): The version number of the package deployed in your environment.
MendixVersion (String): The Mendix version number of the package deployed in your environment.
Production (Boolean): A flag indicating if this environment is a production environment.
3.5.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_PARAMETERS
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
Starts a specific environment that is connected to a specific app to which the authenticated user has access as a regular user. These environments can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/start
3.6.2 Request
Request Parameters
AutoSyncDb (Boolean): Define whether the database should be synchronized automatically with the model during the start phase of the app.
JobId (String): The identifier that can be used to track the progress of the start action
3.6.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_APPID
Invalid AppId
404
APP_NOT_FOUND
App not found
500
NO_MDA_HAS_BEEN_DEPLOYED
Cannot start app. There is no MDA deployed.
500
APP_ALREADY_HAS_A_STARTING_JOB
Cannot start app. There is already a starting job id found.
500
ALREADY_STARTED
Cannot start app. App is already running.
3.6.3.2 Example Output
1
2
3
{"JobId":"02df2e50-0e79-11e4-9191-0800200c9a66",}
3.7 Get Start Environment Status
3.7.1 Description
Retrieve the status of the start environment action.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/start/<JobId>
3.7.2 Request
3.7.2.1 Example Request
1
2
3
4
5
6
GET /api/1/apps/calc/environments/Acceptance/start/02df2e50-0e79-11e4-9191-0800200c9a66
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.7.3 Output
An object with the following key-value pair:
Status (String): Possible values are Starting and Started
3.7.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_PARAMETERS
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
404
ENVIRONMENT_NOT_FOUND
Environment not found
404
NO_SUCH_STARTJOB
Job not found.
500
NO_PACKAGE
Cannot start app. There should be a package configured for this environment.
500
ALREADY_LOCKED
Cannot start app. There is already a lock on this environment.
500
ALREADY_STARTED
Cannot start app. App is already running.
500
DB_SYNC_FAILED
Cannot start app. Synchronization of database failed.
500
INVALID_DB_STRUCTURE
Cannot start app. The database is out-of-sync with the model. Please set AutoSyncDb parameter to true to synchronize the database automatically on startup.
500
MISSING_CONSTANT
Cannot start app. Missing one or more constant values.
500
INSECURE_ADMIN_PASSWORD
Cannot start app. There is a user with administrator role with password ‘1’. This is not allowed.
500
STARTUP_ACTION_FAILED
Cannot start app. Startup action failed.
500
START_FAILED
Cannot start app: result (detail status)
3.7.3.2 Example Output
1
2
3
{"Status":"Starting",}
3.8 Stop Environment
3.8.1 Description
Stops a specific environment that is connected to a specific app to which the authenticated user has access as a regular user. These environments can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/stop
3.8.2 Request
3.8.2.1 Example Request
1
2
3
4
5
6
POST /api/1/apps/calc/environments/Acceptance/stop
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.8.3 Output
3.8.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_PARAMETERS
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
404
ENVIRONMENT_NOT_FOUND
Environment not found
500
STOP_FAILED
Cannot stop app: reason
3.9 Retrieve Environment Package
3.9.1 Description
Retrieves the deployed package of a specific environment that is connected to a specific app to which the authenticated user has access as a regular user. These environments can be found via the “Nodes overview” screen in the Mendix Platform.
1
2
HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/package?url=<Boolean>
3.9.2 Request
3.9.2.1 Request Parameters
AppId (String): Sub-domain name of an app.
Mode (String): The mode of the environment of the app. An environment with this mode should exist.
url (Boolean) (default: false): Indicates whether the API should return a URL pointing to the location of the package.
3.9.2.2 Example Request
1
2
3
4
5
6
GET /api/1/apps/calc/environments/Acceptance/package?url=trueHost: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.9.3 Output
An object with the following key-value pairs:
PackageId (String): Unique identification of the package.
Name (String): Name of the package.
Description (String): Description of the package.
Version (String): Package version. This is also the name of the tag on the project teamserver.
Creator (String): Uploader or creator of this package.
CreationDate (Date): Date that the package became available in the portal. This can be the
upload date or the date that a build was created in the portal.
Status (String): Status of the package. A package is ready to use if the status is ‘Succeeded’.
Possible values: Succeeded, Queued, Building, Uploading and Failed.
Size (Long): Size of the package in bytes.
Url (object): A JSON object containing the following:
Location: The URL pointing to the package file.
TTL: How long the URL is valid (in seconds).
3.9.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_PARAMETERS
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
3.11 Transport a Deployment Package to an Environment
3.11.1 Description
Transports a specific deployment package to a specific environment. After the deployment package has been transported, it will not replace a currently running app automatically. You will need to stop and start the environment to activate the new package.
This call is not available for Free Apps. For a Free App, the Build API can be used to trigger a deployment.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/transport
3.11.2 Request
3.11.2.1 Request Parameters
AppId (String): Sub-domain name of an app.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production, or the name of a flexible environment.
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
400
INVALID_RUNTIME_VERSION
This Runtime version is not supported on this environment.
403
NO_ACCESS
You do not have access
403
TRANSPORT_NOT_ALLOWED
No access to transport to environment ‘mode’.
403
APP_IS_RUNNING
The ‘mode’ environment of ‘app id’ must be stopped to do transport.
403
NOT ALLOWED
Cannot transport - MDA processing failed, try uploading again with a valid MDA.
404
ENVIRONMENT_NOT_FOUND
Environment not found.
404
PACKAGE_NOT_FOUND
Package not found.
500
PACKAGE_PARSE_FAILED
Failed to parse deployment package file.
503
SERVICE UNAVAILABLE
Cannot transport - MDA is still being processed, retry later
3.12 Clean environment
3.12.1 Description
Removes all data from a specific environment: including files and database records. This action requires the environment to be in the status NotRunning.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/clean
3.12.2 Request
3.12.2.1 Request Parameters
AppId (String): Sub-domain name of an app.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production, or the name of a flexible environment.
3.12.2.2 Example Request
1
2
3
4
5
6
POST /api/1/apps/calc/environments/acceptance/clean
Host: deploy.mendix.com
Content-Type: application/json
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6
3.12.3 Output
3.12.3.1 Error Codes
HTTP Status
Error code
Description
400
INVALID_PARAMETERS
Not enough parameters given. Please set AppId and Mode parameters.
400
INVALID_ENVIRONMENT
Could not parse environment mode ‘mode’. Valid options are Test, Acceptance, Production or the name of a flexible environment.
403
ENVIRONMENT_NOT_STOPPED
Environment needs to be stopped.
404
ENVIRONMENT_NOT_FOUND
Environment not found.
422
ENVIRONMENT_NOT_DEPLOYED
No app deployed to the environment.
500
ENVIRONMENT_CLEAN_FAILED
Unable to clean the environment. Please contact Support.
Changes the values of existing environment settings like custom settings, constants, and scheduled events. These changes are applied after restarting the environment.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/settings
3.14.2 Request
3.14.2.1 Request Parameters
AppId (String): Subdomain name of an app.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production, or the name of a flexible environment.
Body: JSON collection retrieved with GET method at the same URI
Scale memory and instances of an environment. Only those environments that run a package that uses a supported version of the Mendix Runtime can spread the total memory over multiple instances.
1
2
HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/environments/<Mode>/scale
3.15.2 Request
3.15.2.1 Request Parameters
AppId (String): Subdomain name of an app.
Mode (String): Mode of the environment. Possible values: Test, Acceptance, Production, or the name of a flexible environment.