Manage Cloud application versions¶
Info
Learn the concepts and fundamentals of versions in the Explanation page.
An app version represents a specific executable code. You can think of a version like a Git commit tag. It is a snapshot of the code at a specific point in time.
This how-to guide explains how to interact with versions using the
/v1/applications/{application_id}/versions endpoints. Go to the reference
section to see all the available parameters for each
endpoint.
Create a version¶
Use the POST /v1/applications/{application_id}/versions
endpoint to create a new version for an application, using the latest pushed
executable. The endpoint requires an id in the request payload, so generate
one yourself if you don't want to choose a custom one:
{
"id": "version-28061488",
"application_id": "humming-cricket",
"name": "version-28061488",
"description": "",
"executable": {
"id": "version-28061488",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:14:57.601746513Z",
"updated_at": "2026-07-29T06:14:57.601746513Z"
}
The call above uses a randomly generated ID, and the same identifier for the
version name. The name of the version is used as a human-readable label. You
can pass different values for the id and name fields in the payload to
specify a custom ID and name for the version. For example:
{
"id": "v0.0.1",
"application_id": "humming-cricket",
"name": "Initial version",
"description": "",
"executable": {
"id": "v0.0.1",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:15:12.365713988Z",
"updated_at": "2026-07-29T06:15:12.365713988Z"
}
Get a version¶
Use the GET /v1/applications/{application_id}/versions/{version_id}
endpoint to retrieve an existing version for an application by its ID.
{
"id": "v0.0.1",
"application_id": "humming-cricket",
"name": "Initial version",
"description": "",
"executable": {
"id": "v0.0.1",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:15:12.365713988Z",
"updated_at": "2026-07-29T06:15:12.365713988Z"
}
You can list all versions in the application using the GET
/v1/applications/{application_id}/versions endpoint. The
same information is displayed as for the individual versions, but as an array
of objects. This endpoint is paginated, so the snippet below always uses
pagination: it passes pagereturn=true to receive a next_page_token in the
response, and keeps requesting pages by passing that token back as
pagetoken until no token is returned.
ITEMS="[]"
PAGE_TOKEN=""
while :; do
RESPONSE=$(curl -s -G "https://api.cloud.nextmv.io/v1/applications/humming-cricket/versions" \
-H "Authorization: Bearer ${NEXTMV_API_KEY}" \
--data-urlencode "pagereturn=true" \
--data-urlencode "pagetoken=${PAGE_TOKEN}")
ITEMS=$(jq -n --argjson existing "$ITEMS" --argjson page "$(echo "$RESPONSE" | jq '.items')" '$existing + $page')
PAGE_TOKEN=$(echo "$RESPONSE" | jq -r '.next_page_token // empty')
[ -z "$PAGE_TOKEN" ] && break
done
echo "$ITEMS" | jq '.'
[
{
"id": "v0.0.1",
"application_id": "humming-cricket",
"name": "Initial version",
"description": "",
"executable": {
"id": "v0.0.1",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:15:12.365713988Z",
"updated_at": "2026-07-29T06:15:12.365713988Z"
},
...
{
"id": "version-28061488",
"application_id": "humming-cricket",
"name": "version-28061488",
"description": "",
"executable": {
"id": "version-28061488",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:14:57.601746513Z",
"updated_at": "2026-07-29T06:14:57.601746513Z"
}
]
Update a version¶
You can update different attributes of a version using the PUT
/v1/applications/{application_id}/versions/{version_id}
endpoint, such as its:
- Name
- Description
Please note that you cannot change the executable associated with a version or the version ID. Once a version is created, the executable code will always be attached to this version no matter how many other ones are published. This is, the code is versioned. You can create as many versions from an executable as you want.
The endpoint expects the full version payload, so get the version first and merge in the fields you want to change.
The snippet below does this in three steps: it sends a GET request to fetch
the current version, uses jq to merge the name and description fields
into that response, and pipes the merged payload to a PUT request that
updates the version.
curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/humming-cricket/versions/v0.0.1" \
-H "Authorization: Bearer ${NEXTMV_API_KEY}" \
| jq '. + {"name": "Beta deliverable", "description": "Pre-alpha launch"}' \
| curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/humming-cricket/versions/v0.0.1" \
-H "Authorization: Bearer ${NEXTMV_API_KEY}" \
-H "Content-Type: application/json" \
-d @- \
| jq '.'
{
"id": "v0.0.1",
"application_id": "humming-cricket",
"name": "Beta deliverable",
"description": "Pre-alpha launch",
"executable": {
"id": "v0.0.1",
"user_email": "sebastian@nextmv.io",
"uploaded_at": "2026-07-29T06:14:48.307266906Z",
"requirements": {
"executable_type": "python",
"runtime": "ghcr.io/nextmv-io/runtime/python:3.11",
"options": {
"strict": false,
"validation": {
"enforce": "none"
},
"items": [
{
"name": "details",
"description": "Print details to logs. Default true.",
"option_type": "bool",
"required": false,
"default": true,
"ui": {
"control_type": "toggle",
"display_name": "Details"
}
}
]
},
"io_configuration": {
"format": "json"
}
}
},
"created_at": "2026-07-29T06:15:12.365713988Z",
"updated_at": "2026-07-29T06:15:34.925565262Z"
}
Delete a version¶
Warning
Deleting a version is irreversible. All the version's data will be permanently deleted.
Delete a version using the DELETE
/v1/applications/{application_id}/versions/{version_id}
endpoint.