Deploy API – Version 2

Last modified: October 19, 2026

Introduction

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

Authentication

The Deploy API v2 supports authentication via a personal access token (PAT) or an API key. Mendix recommends using a PAT.

Authenticating with a PAT

For details on how to generate a PAT, see the Personal Access Tokens section of Mendix Profile.

Select at least the following scopes:

  • mx:deployment:read – to perform GET operations
  • mx:deployment:write – to perform all operations (GET, POST, PUT, and DELETE)
  • mx:build:read – to read build information
  • mx:build:write – to trigger and manage builds

Each request must contain an Authorization header with the value MxToken {GENERATED_PAT}. Here is an example:

GET /api/v2/apps/calc/jobs/66046953-ecf7-4550-a889-4b7e9f1e1705 HTTP/1.1
Host: deploy.mendix.com
Authorization: MxToken 7LJE…vk

Authenticating with an API Key

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

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

Migrating from an API Key to a PAT

To switch an existing integration from an API key to a PAT, do the following:

  1. Generate a PAT with the required scopes.
  2. Remove the Mendix-Username and Mendix-ApiKey headers.
  3. Add an Authorization header with the value MxToken {GENERATED_PAT}.
  4. Run your integration to verify that the calls succeed.

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 Access 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