Manage Cloud applications¶
Info
Learn the concepts and fundamentals of applications in the Explanation page.
A Nextmv application is an entity that contains a decision model as executable code.
This how-to guide explains how to interact with applications using the
/v1/applications endpoints. Go to the reference section
to see all the available parameters for each endpoint.
Create an app¶
Use the POST /v1/applications endpoint to create a new application. The
endpoint requires an id in the request payload, so generate one yourself if
you don't want to choose a custom one:
The call above uses a randomly generated ID, and the same identifier for the
app's name. The name of the application 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 application. For example:
When working with Nextpipe and decision worklows, you must specify
that an application is of type "workflow" at the time of creation. Use the
is_pipeline field in the request payload to create a workflow application:
{
"name": "quirky-rabbit-workflow",
"id": "quirky-rabbit-workflow",
"description": "",
"type": "pipeline",
"default_instance": "",
"default_experiment_instance": "",
"subscription_id": "",
"locked": false,
"created_at": "2026-07-29T05:03:08.392940536Z",
"updated_at": "2026-07-29T05:03:08.392940536Z"
}
Get an app¶
Use the GET /v1/applications/{application_id} endpoint to retrieve an
existing application by its ID.
You can list all applications in the account using the GET /v1/applications
endpoint. The same information is displayed as for the individual
applications, 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" \
-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 '.'
[
{
"name": "quirky-rabbit-workflow",
"id": "quirky-rabbit-workflow",
"description": "",
"type": "pipeline",
"default_instance": "",
"default_experiment_instance": "",
"subscription_id": "",
"locked": false,
"created_at": "2026-07-29T05:13:23.278728128Z",
"updated_at": "2026-07-29T05:13:23.278728128Z"
},
...
{
"name": "A quirky rabbit",
"id": "quirky-rabbit",
"description": "",
"type": "custom",
"default_instance": "",
"default_experiment_instance": "",
"subscription_id": "",
"locked": false,
"created_at": "2026-07-29T05:13:08.998894324Z",
"updated_at": "2026-07-29T05:13:08.998894324Z"
}
]
Update an app¶
You can update different attributes of an application using the
PUT /v1/applications/{application_id} endpoint, such as its:
- Name
- Description
- Default instance ID
- Default experiment instance ID
Please note that you cannot update the type of an application or its ID after it has been created. The endpoint expects the full application payload, so get the application 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 application, uses jq to merge the description field into that
response, and pipes the merged payload to a PUT request that updates the
application.
curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/quirky-rabbit" \
-H "Authorization: Bearer ${NEXTMV_API_KEY}" \
| jq '. + {"description": "This application inspects the quirks of rabbits"}' \
| curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/quirky-rabbit" \
-H "Authorization: Bearer ${NEXTMV_API_KEY}" \
-H "Content-Type: application/json" \
-d @- \
| jq '.'
{
"name": "A quirky rabbit",
"id": "quirky-rabbit",
"description": "This application inspects the quirks of rabbits",
"type": "custom",
"default_instance": "",
"default_experiment_instance": "",
"subscription_id": "",
"locked": false,
"created_at": "2026-07-29T05:02:32.153465767Z",
"updated_at": "2026-07-29T05:03:37.195706528Z"
}
Delete an app¶
Warning
Deleting an application is irreversible. All the app's data, such as its runs, instances, and experiments, will be permanently deleted.
Delete an application using the DELETE /v1/applications/{application_id}
endpoint.