Manage Cloud application instances¶

Info

Learn the concepts and fundamentals of instances in the Explanation page.

An application instance is a representation of a version and optional configuration (including options/parameters). Instances are the mechanism by which a run is made.

This how-to guide explains how to interact with instances using the /v1/applications/{application_id}/instances endpoints. Go to the reference section to see all the available parameters for each endpoint.

Create an instance¶

Use the POST /v1/applications/{application_id}/instances endpoint to create a new instance. The endpoint requires an id, a name, and a version_id in the request payload, so generate an ID yourself if you don't want to choose a custom one:

BashOutput

INSTANCE_ID="instance-$(openssl rand -hex 4)"

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"${INSTANCE_ID}\", \"name\": \"${INSTANCE_ID}\", \"version_id\": \"version-28061488\"}" \
  | jq '.'

{
  "name": "instance-4086b4e6",
  "id": "instance-4086b4e6",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-29T06:28:02.690348988Z",
  "updated_at": "2026-07-29T06:28:02.690348988Z"
}

The call above uses a randomly generated ID, and the same identifier for the instance's name. The name of the instance 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 instance. For example:

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"id": "production", "name": "The main production instance", "version_id": "version-28061488"}' \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-29T06:28:06.607789523Z",
  "updated_at": "2026-07-29T06:28:06.607789523Z"
}

You can configure the instance at the time of creation. Use the configuration field in the request payload, passing an ExecutionConfiguration object, to set attributes such as:

execution_class: the execution class to use for runs created on this instance.
queuing: a queuing object used to configure queuing for runs created on this instance. Set disabled: true to disable queuing, and use the priority field to set the queuing priority.
options: the default options to use for runs created on this instance, as a dictionary of key-value pairs.

Go the reference section to see all the available attributes for configuring an instance. Consider the following example where an instance is created with customized configuration:

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "staging",
    "name": "staging",
    "version_id": "version-28061488",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "options": {"details": "false"},
      "queuing": {"priority": 2, "disabled": true}
    }
  }' \
  | jq '.'

{
  "name": "staging",
  "id": "staging",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "false"
    },
    "queuing": {
      "priority": 2,
      "disabled": true
    }
  },
  "locked": false,
  "created_at": "2026-07-29T06:28:23.271843928Z",
  "updated_at": "2026-07-29T06:28:23.271843928Z"
}

Get an instance¶

Use the GET /v1/applications/{application_id}/instances/{instance_id} endpoint to retrieve an existing instance by its ID.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances/production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-29T06:28:06.607789523Z",
  "updated_at": "2026-07-29T06:28:06.607789523Z"
}

You can list all instances in the application using the GET /v1/applications/{application_id}/instances endpoint. The same information is displayed as for the individual instances, 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.

BashOutput

ITEMS="[]"
PAGE_TOKEN=""

while :; do
  RESPONSE=$(curl -s -G "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances" \
    -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": "Latest",
    "id": "latest",
    "application_id": "humming-cricket",
    "version_id": "",
    "description": "Auto-created instance to manage the latest pushed executable binary.",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-29T06:14:48.313783401Z",
    "updated_at": "2026-07-29T06:14:48.313783401Z"
  },
  ...
  {
    "name": "The main production instance",
    "id": "production",
    "application_id": "humming-cricket",
    "version_id": "version-28061488",
    "description": "",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-29T06:28:06.607789523Z",
    "updated_at": "2026-07-29T06:28:06.607789523Z"
  }
]

The latest instance is the default instance of an application and is automatically created when an application is created. The latest instance always points to the latest pushed executable. You cannot delete the latest instance.

Update an instance¶

You can update attributes of an instance and its configuration with the PUT /v1/applications/{application_id}/instances/{instance_id} endpoint, such as its:

Name
Description
Version ID
Execution class
Queuing priority

Go the reference section to see all the available fields for updating an instance. The fields are similar to the ones available when creating an instance.

The endpoint expects the full instance payload, so get the instance 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 instance, uses jq to merge the configuration field into that response, and pipes the merged payload to a PUT request that updates the instance.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances/production" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '. + {"configuration": {"options": {"details": "true"}, "queuing": {"priority": 9}}}' \
  | curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances/production" \
      -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "true"
    },
    "queuing": {
      "priority": 9,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-29T06:28:06.607789523Z",
  "updated_at": "2026-07-29T06:29:09.272566371Z"
}

To lock and unlock an instance, use a separate request to the PUT /v1/applications/{application_id}/instances/{instance_id}/lock endpoint, passing true or false for the locked field, respectively. You can only update the locked status of an instance through this endpoint, not when creating it.

You cannot update the instance ID. For the latest instance, you cannot update the version ID, as it is always associated to the latest pushed executable.

BashOutput

curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances/production/lock" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"locked": true}' \
  | jq '.'

{
  "name": "The main production instance",
  "id": "production",
  "application_id": "humming-cricket",
  "version_id": "version-28061488",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "true"
    },
    "queuing": {
      "priority": 9,
      "disabled": false
    }
  },
  "locked": true,
  "created_at": "2026-07-29T06:28:06.607789523Z",
  "updated_at": "2026-07-29T06:29:13.906314525Z"
}

Delete an instance¶

Warning

Deleting an instance is irreversible. All the instance's data will be permanently deleted.

Info

You cannot delete the latest instance.
You cannot delete locked instances. You must unlock the instance before deleting it.

Delete an instance using the DELETE /v1/applications/{application_id}/instances/{instance_id} endpoint.

Bash

curl -s -X DELETE "https://api.cloud.nextmv.io/v1/applications/humming-cricket/instances/staging" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}"