Deploy API – Version 2

Last modified: October 28, 2024

Introduction

The Deploy API allows you to manage application environments in Mendix Cloud. Version 2 introduces improved APIs for some actions.

The Deploy API v2 requires authentication via API keys that are bound to your Mendix account.

Obtaining an API Key

To obtain a Mendix API key, follow the instructions in the API Keys section of Mendix Profile.

Using Authentication Headers

Use the following request headers to authenticate an API call:

  • Mendix-Username – the login name of the requesting user with the required privileges in the Mendix Platform
  • Mendix-ApiKey – the API key of this user

Configuring Permissions

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, API access must be explicitly allowed for team members who want to use the Deploy API.

To perform an action via the Deploy API, such as transporting a new deployment package, you need API Rights and Transport Rights permissions. This can be configured from the Permissions tab of your app’s Environments page.

API Calls

Upload Package

Description

Uploads a deployment package from the local system to a specific app. This package can then be transported to a specific environment for deployment.

HTTP Method: POST
URL: https://deploy.mendix.com/api/v2/apps/<AppId>/packages/upload?name=<PackageName>

Request

Request Parameters
Example Request
POST /api/v2/apps/calc/packages/upload?name=calc_1.0.0.45.mda
Host: deploy.mendix.com

Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6
Content-Type: multipart/form-data; boundary=MultipartBoundary

--MultipartBoundary
Content-Disposition: form-data;

@%USERPROFILE%/Documents/Mendix/calc-main/releases/calc_1.0.0.45.mda
--MultipartBoundary--

curl example:

curl -v -F "file=@%USERPROFILE%/Documents/Mendix/calc-main/releases/calc_1.0.0.45.mda"  -X POST -H "Mendix-Username: richard.ford51@example.com" -H "Mendix-ApiKey: 26587896-1cef-4483-accf-ad304e2673d6" "https://deploy.mendix.com/api/v2/apps/calc/packages/upload?name=calc_1.0.0.45.mda"

Output

The API call returns the following JSON:

{
    "PackageId": "<packageID>",
    "JobId": "<JobID>"
}

Where:

  • <packageID> is the ID of the package which will be created by the API
  • <JobID> is the ID of the job that is creating the package — the status of the job can be interrogated with the Job Status API

Job Status

Description

Find the status of a job using the JobID returned from an API call.

HTTP Method: GET
URL: https://deploy.mendix.com/api/v2/apps/<AppId>/jobs/<JobId>

Request

Request Parameters
  • AppId (String): Subdomain name of an app
  • JobID (String): the ID of a job that was triggered by a previous API call
Example Request
GET /api/v2/apps/calc/jobs/66046953-ecf7-4550-a889-4b7e9f1e1705
Host: deploy.mendix.com

Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

Output

The API call returns the following JSON:

{
    "Status": "<status>"
}

Where <status> is one of the following:

  • Queued
  • Running
  • Completed
  • Failed