curl --request POST \
  -H 'Content-Type: application/json' \
  -H 'OAUTH-TOKEN: <your-oauth-token>' \
  -d '{
        "deployment": {
          "source": {
            "head": {
              "name": "main"
            },
            "name": "Add feature X",
            "version": "abc123def456"
          },
          "stage": {
            "branch": {
              "name": "deploy-main"
            },
            "environment": "production",
            "target_directory": "/home/src/project_name"
          }
        },
        "api_key": "zkWlN0PkIKSN0C11CfUHUj84OT5XOJ6tDZ6bDRO2"
      }' \
  --url https://your-mage-instance.com/api/deployment_settings/prod/deployments

Trigger a deployment using a specific deployment setting.

POST /deployment_settings/{setting_name}/deployments

​
setting_name
string
required

Name of the deployment setting to use for this deployment. Find the deployment setting name on your Mage Pro cluster’s /apps/deploy page.

​
deployment.source.head.name
string
required

The name of the GitHub branch where the commit is located (e.g., main, feature/xyz).

​
deployment.source.name
string
required

A human-readable description of the commit (e.g., GitHub commit message).

​
deployment.source.version
string
required

The GitHub commit SHA that will be deployed.

​
deployment.stage.branch.name
string
required

The branch name in the target deployment environment (e.g., deploy-main).

​
deployment.stage.environment
string
required

The environment where the deployment will be created (e.g., development, staging, production).

​
deployment.stage.target_directory
string

Optional. The directory path inside the deployment environment where the code will be deployed.

curl --request POST \
  -H 'Content-Type: application/json' \
  -H 'OAUTH-TOKEN: <your-oauth-token>' \
  -d '{
        "deployment": {
          "source": {
            "head": {
              "name": "main"
            },
            "name": "Add feature X",
            "version": "abc123def456"
          },
          "stage": {
            "branch": {
              "name": "deploy-main"
            },
            "environment": "production",
            "target_directory": "/home/src/project_name"
          }
        },
        "api_key": "zkWlN0PkIKSN0C11CfUHUj84OT5XOJ6tDZ6bDRO2"
      }' \
  --url https://your-mage-instance.com/api/deployment_settings/prod/deployments