Api

Applications API Endpoints & Usage

Technical reference for the Nextmv Cloud API for applications.

The applications API endpoints can be used to manage, run, and deploy applications to Nextmv Cloud. They are also used to create and manage experiments for each application. See the Nextmv CLI reference for equivalent Nextmv CLI functionality.

Note, all requests must be authenticated with Bearer Authentication. Make sure your request has a header containing your Nextmv Cloud API key, as such:

  • Key: Authorization
  • Value: Bearer <YOUR-API-KEY>
Authorization: Bearer <YOUR-API-KEY>
Copy

Run execution

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs

New application run.

Create new application run.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}

Get run result.

Get the result of a run.

Run management

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs

List past runs (50 max).

List past runs for application (50 max).

PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}

Update name and description of run.

Update the name and/or description of a run.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}/metadata

Get run status without output.

Get the status of a run without the output.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/{run_id}/input

Get run input.

Gets the input used for a run.

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/runs/uploadurl

Retrieve unique upload URL and ID.

Retrieve a unique URL and ID for uploading run input (for large input files).

Versions

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/versions

Create new version.

Create new application version using the current dev binary.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/versions

List versions.

List all versions for an application.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/versions/{version_id}

Get version information.

Get application version information specified by application and version ID.

PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}/versions/{version_id}

Update version information.

Update application version information with defined data, specified by application and version ID.

DELETEhttps://api.cloud.nextmv.io/v1/applications/{application_id}/versions/{version_id}

Delete version.

Delete version, specified by application and version ID.

Instances

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances

Create new instance.

Create new application instance for a specified version.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances

List instances.

List all instances for an application.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances/{instance_id}

Get instance information.

Get application instance information specified by application and instance ID.

PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances/{instance_id}

Update an instance.

Update application instance information with defined data, specified by application and instance ID.

DELETEhttps://api.cloud.nextmv.io/v1/applications/{application_id}/instances/{instance_id}

Delete instance.

Delete application instance, specified by application and instance ID.

Experiments

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/inputsets

Create new input set.

Create new application input set for experiments.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/inputsets

List input sets.

List all input sets for an application.

PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/inputsets/{input_set_id}

Update input set metadata.

Update input set metadata with defined data, specified by application and input set ID.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/inputsets/{input_set_id}

Get input set information.

Get input set information specified by application and input set ID.

POSThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/batch

Create and start batch experiment.

Create and start batch experiment.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/batch

List batch experiments.

List batch experiments for an application.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/batch/{batch_id}

Get batch experiment status and results.

Get batch experiment status and results specified by application and batch ID.

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}/experiments/batch/{batch_id}/runs

List batch experiment runs.

List runs used for batch experiment specified by application and batch ID.

Admin

GEThttps://api.cloud.nextmv.io/v1/applications/{application_id}

Get application information.

Get application information specified by application ID.

PUThttps://api.cloud.nextmv.io/v1/applications/{application_id}

Update application information.

Update application information with defined data, specified by application ID.

DELETEhttps://api.cloud.nextmv.io/v1/applications/{application_id}

Delete application.

Delete application, specified by application ID.

Usage

Below we provide an example of how to use the API in Python. You will need to get your API key and set the following environment variable:

export NEXTMV_API_KEY=YOUR_NEXTMV_CLOUD_API_KEY_HERE
Copy

Be sure to replace YOUR_APP_ID with the id of the Nextmv app you wish to call in the code snippet below.

#!/usr/bin/env python3
import datetime
import json
import os
import sys
import time

import requests

NEXTMV_API_KEY = os.environ['NEXTMV_API_KEY']
BASE_URL = 'https://api.cloud.nextmv.io/v1/applications/YOUR_APP_ID'

def solve(data: str) -> dict:
    # Send input to the app and create a run.
    headers = {
        'Authorization': f'Bearer {NEXTMV_API_KEY}',
        'Content-Type': 'application/json',
        'accept': 'application/json',
    }
    params = {'instance_id': 'latest'}
    response = requests.post(
        f'{BASE_URL}/runs',
        data=data,
        headers=headers,
        params=params
    )
    response.raise_for_status()
    run_id = response.json()['run_id']

    # Poll job status until it is finished.
    start = datetime.datetime.now()
    wait_time = 0.2
    wait_max = 5
    timeout = 60
    while True:
        # Check for timeout.
        if (datetime.datetime.now() - start).total_seconds() > timeout:
            raise Exception(f'timed out after {timeout}')

        # Get job status.
        response = requests.get(
            f'{BASE_URL}/runs/{run_id}',
            headers=headers,
        )
        response.raise_for_status()
        status = response.json()['metadata']['status']
        if status == 'running':
            time.sleep(wait_time)
            wait_time = min(wait_time * 2, wait_max)
        elif status == 'succeeded':
            break
        else:
            error = response.json()['metadata']['error']
            raise Exception(f'run failed with status: {status}; error: {error}')

    return response.json()

def main():
    data = {'input': json.load(open(sys.argv[1]))}
    result = solve(json.dumps(data))
    print(json.dumps(result, ensure_ascii=False, indent=4))


if __name__ == '__main__':
    main()
Copy

    Save the code snippet to a file (e.g., as main.py) and use it to execute a run with a valid input (e.g., input.json):

    ./main.py input.json
    
    Copy

    Page last updated

    Go to on-page nav menu