Skip to main content

Promote App to Next Environment

POST/apps/{appId}/promote

Pulls the latest version of an app from the configured Git repository and promotes it to the next environment in your pipeline. Promotion moves the app forward by one step — for example, development → staging, or staging → production. It does not skip environments or jump directly to production. If there is no higher environment to promote to, the call returns a 500 error.

Path Parameters
appIdstringrequired
ID of the app to promote.
Error Responses
400
Invalid UUID, MULTI_ENVIRONMENT check failed, or the app version is still in DRAFT state.
401
Missing or invalid Authorization token.
403
Insufficient permissions to promote this app.
404
App not found.
406
currentEnvironmentId is stale — the version has already been promoted.
500
No higher-priority environment exists to promote to.
Request
curl -X POST "https://{your-domain}/api/ext/apps/{appId}/promote" \
  -H "Authorization: Basic <access_token>" \
  -H "Content-Type: application/json"
Response — 200
{
"editorEnvironment": {
  "id": "env-uuid-staging",
  "organizationId": "45892c81-c1f0-48c6-8875-c2e4fca516f8",
  "name": "staging",
  "isDefault": false,
  "priority": 2,
  "enabled": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-05-01T10:00:00.000Z"
},
"environments": [
  {
    "id": "env-uuid-dev",
    "name": "development",
    "priority": 1,
    "enabled": true,
    "appVersionsCount": 3
  },
  {
    "id": "env-uuid-staging",
    "name": "staging",
    "priority": 2,
    "enabled": true,
    "appVersionsCount": 2
  }
]
}