Maintenance Admin API

Put an upgrade package in place

POST /api/v1/upgrade/stage

The first step of an upgrade from outside, the same upgrade the upgrade page runs: give the package as an uploaded patch file, or as a url the installation downloads it from. It is checked and kept until an upgrade starts; nothing is applied yet. Only for an admin allowed to manage upgrades.

The steps, in order: stage, preflight, launch test, start, then follow the progress until the run is done, and clear the code cache.

Request body multipart/form-data
patch file required
The upgrade package (zip).
Request body application/x-www-form-urlencoded
url string (uri) required
Where the installation downloads the package from.
timeout integer
Seconds the download may take: 60 to 1800.
Default: 600
Responses
200 The package is in place.
400 The package could not be downloaded or is not a valid package; the message says why.
401 The token is missing or wrong (Unauthenticated.), or its user may not act on this object (Unauthorized). Without the Accept: application/json header, a missing or wrong token answers with a redirect to the sign-in page instead.
403 The token's admin may not manage upgrades.
409 An upgrade is in progress: already_running with its run_id, or busy while one of its steps holds the lock.
422 Neither patch nor url, a URL that is not http or https, a timeout out of range, or a failed upload.
Put an upgrade package in place · multipart/form-data
1 2 3 4
curl -X POST 'https://your-domain/api/v1/upgrade/stage' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F 'patch=@patch.zip'
Put an upgrade package in place · application/x-www-form-urlencoded
1 2 3 4 5
curl -X POST 'https://your-domain/api/v1/upgrade/stage' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode 'url=https://example.com/patch.zip' \
  --data-urlencode 'timeout=600'
Response
{
    "status": "staged",
    "from": "4.2.0-p180",
    "to": "4.2.0-p194"
}