Using managed inputs¶

Info

Learn the concepts and fundamentals of managed inputs in the Explanation page.

Managed inputs are used to store and keep track of your inputs. They can be created either by referencing a prior run within your application, or by uploading new data. You can use managed inputs for runs as well as other features of the Nextmv Platform:

Scenario tests: when creating a scenario test, you can define scenarios using managed inputs as the data source.
Input sets: use them to create batch experiments or scenario tests. When creating an input set, you can define one or more managed inputs to make up the input set.

Included in this how-to guide are instructions on how to interact with managed inputs using the /v1/applications/{application_id}/inputs endpoints. Go to the reference section to see all the available parameters for each endpoint.

Create a managed input¶

Use the POST /v1/applications/{application_id}/inputs endpoint to create a new managed input for an application. Managed inputs can be created by one of the following methods:

From a run, by providing the run_id field in the request payload.
From a file (or directory) that is uploaded to Nextmv Cloud, by providing the upload_id field in the request payload.

To know which type of content format is expected for the managed input, we recommend you specify the format field in the request payload, setting the format.input.type attribute to a value such as json.

Here is an example that creates a json managed input from an existing run ID. The endpoint requires an id and name in the request payload, so generate an ID yourself if you don't want to choose a custom one, and use it as the name too:

BashOutput

MANAGED_INPUT_ID="managed-input-$(openssl rand -hex 4)"

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"${MANAGED_INPUT_ID}\",
    \"name\": \"${MANAGED_INPUT_ID}\",
    \"run_id\": \"latest-fDy89wEvR\",
    \"format\": {\"input\": {\"type\": \"json\"}}
  }" \
  | jq '.'

{
  "id": "managed-input-424a6495",
  "name": "managed-input-424a6495",
  "description": "",
  "app_id": "",
  "run_id": "latest-fDy89wEvR",
  "upload_id": "",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-29T14:30:34.811089656Z",
  "updated_at": "2026-07-29T14:30:34.811089656Z"
}

If you have data in the filesystem that you want to upload as a managed input, there are a couple more steps to complete.

Create a new upload using the POST /v1/applications/{application_id}/runs/uploadurl endpoint.

UPLOAD_RESPONSE=$(curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs/uploadurl" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}")

The returned object contains an upload_id and an upload_url. Let's use the upload_url to upload the actual data to Nextmv Cloud with a PUT request. This can be a file (json) or a directory (multi-file).

UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_url')
UPLOAD_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_id')

curl -s -X PUT "$UPLOAD_URL" \
  --data-binary '{"name": "world", "radius": 6378, "distance": 147.6}'

Once the data has been uploaded, we can create a managed input from it, by using the upload_id that was returned when the upload was created.

BashOutput

UPLOAD_RESPONSE=$(curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs/uploadurl" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_url')
UPLOAD_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_id')

curl -s -X PUT "$UPLOAD_URL" \
  --data-binary '{"name": "world", "radius": 6378, "distance": 147.6}'

MANAGED_INPUT_ID="managed-input-$(openssl rand -hex 4)"

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"${MANAGED_INPUT_ID}\",
    \"name\": \"${MANAGED_INPUT_ID}\",
    \"upload_id\": \"${UPLOAD_ID}\",
    \"format\": {\"input\": {\"type\": \"json\"}}
  }" \
  | jq '.'

{
  "id": "managed-input-c72d3979",
  "name": "managed-input-c72d3979",
  "description": "",
  "app_id": "",
  "run_id": "",
  "upload_id": "771696fa-c1d5-474f-9437-8717f8a313c2",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-29T14:30:45.073976423Z",
  "updated_at": "2026-07-29T14:30:45.073976423Z"
}

For multi-file, just set the format.input.type field to multi-file. When uploading data, package your directory into a tar file first, the same way as shown in the multi-file section of the run guide, and upload that tar file to the upload URL instead.

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

BashOutput

UPLOAD_RESPONSE=$(curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs/uploadurl" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_url')
UPLOAD_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_id')

curl -s -X PUT "$UPLOAD_URL" \
  --data-binary '{"name": "world", "radius": 6378, "distance": 147.6}'

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"baxter-burrow\",
    \"name\": \"The managed input of Baxter's Burrow\",
    \"upload_id\": \"${UPLOAD_ID}\",
    \"format\": {\"input\": {\"type\": \"json\"}}
  }" \
  | jq '.'

{
  "id": "baxter-burrow",
  "name": "The managed input of Baxter's Burrow",
  "description": "",
  "app_id": "",
  "run_id": "",
  "upload_id": "68ba4714-0b3b-4881-8a66-e9c104e7faa7",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-29T14:31:20.615973444Z",
  "updated_at": "2026-07-29T14:31:20.615973444Z"
}

Run with a managed input¶

Once a managed input has been created you can use it to start a run by means of the input_id field in the request payload of the POST /v1/applications/{application_id}/runs endpoint.

BashOutput

curl -s -X POST "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs?instance_id=latest" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"input_id": "baxter-burrow"}' \
  | jq '.'

{
  "run_id": "latest-a-AxX9QPDg"
}

Once the run is submitted, you can retrieve its metadata with the GET /v1/applications/{application_id}/runs/{run_id}/metadata endpoint, and its result with the GET /v1/applications/{application_id}/runs/{run_id} endpoint. Please read our documentation on run polling to learn how to wait for a run to finish before retrieving its results.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs/latest-a-AxX9QPDg/metadata" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '.'

{
  "id": "latest-a-AxX9QPDg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:31:30Z",
    "initiated_at": "2026-07-29T14:31:30.564327627Z",
    "duration": 4196,
    "execution_duration": 3699,
    "input_size": 61,
    "output_size": 913,
    "error": "",
    "application_id": "uncanny-rodent",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    },
    "tracking": {
      "input_id": "baxter-burrow"
    }
  }
}

Notice the .metadata.tracking.input_id field, which shows the ID of the managed input that was used for the run.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/runs/latest-a-AxX9QPDg" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq 'del(.output.assets)'

{
  "id": "latest-a-AxX9QPDg",
  "user_email": "sebastian@nextmv.io",
  "name": "",
  "description": "",
  "metadata": {
    "status": "succeeded",
    "status_v2": "succeeded",
    "created_at": "2026-07-29T14:31:30Z",
    "initiated_at": "2026-07-29T14:31:30.564327627Z",
    "duration": 4196,
    "execution_duration": 3699,
    "input_size": 61,
    "output_size": 913,
    "error": "",
    "application_id": "uncanny-rodent",
    "application_instance_id": "latest",
    "application_version_id": "",
    "execution_class": "6c9500mb870s",
    "runtime": "python-3_11",
    "run_type": {
      "type": "standard",
      "definition_id": "",
      "reference_id": ""
    },
    "format": {
      "input": {
        "type": "json"
      },
      "output": {
        "type": "json"
      }
    },
    "options": {
      "active_options": {
        "details": "true"
      },
      "request_options": null,
      "options_summary": [
        {
          "name": "details",
          "value": "true",
          "source": "version"
        }
      ]
    },
    "queuing_priority": 6,
    "queuing_disabled": false,
    "metrics": {
      "message": "Hello, world",
      "value": 1.23
    },
    "tracking": {
      "input_id": "baxter-burrow"
    }
  },
  "output": {
    "options": {
      "details": true
    },
    "solution": {
      "message": "Hello, world"
    },
    "metrics": {
      "value": 1.23,
      "message": "Hello, world"
    }
  }
}

.output.assets was removed from the response above for a cleaner display.

Get a managed input¶

Use the GET /v1/applications/{application_id}/inputs/{input_id} endpoint to retrieve an existing managed input for an application by its ID.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs/baxter-burrow" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq 'del(.download_url)'

{
  "id": "baxter-burrow",
  "name": "The managed input of Baxter's Burrow",
  "description": "",
  "app_id": "uncanny-rodent",
  "run_id": "",
  "upload_id": "68ba4714-0b3b-4881-8a66-e9c104e7faa7",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-29T14:31:20.615973444Z",
  "updated_at": "2026-07-29T14:31:20.615973444Z"
}

.download_url was removed from the response above for a cleaner display.

You can list all managed inputs in the application using the GET /v1/applications/{application_id}/inputs endpoint. 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/uncanny-rodent/inputs" \
    -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 '.[0:3]'

[
  {
    "id": "baxter-burrow",
    "name": "The managed input of Baxter's Burrow",
    "description": "",
    "app_id": "uncanny-rodent",
    "run_id": "",
    "upload_id": "68ba4714-0b3b-4881-8a66-e9c104e7faa7",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-29T14:31:20.615973444Z",
    "updated_at": "2026-07-29T14:31:20.615973444Z"
  },
  {
    "id": "managed-input-c72d3979",
    "name": "managed-input-c72d3979",
    "description": "",
    "app_id": "uncanny-rodent",
    "run_id": "",
    "upload_id": "771696fa-c1d5-474f-9437-8717f8a313c2",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-29T14:30:45.073976423Z",
    "updated_at": "2026-07-29T14:30:45.073976423Z"
  },
  {
    "id": "managed-input-424a6495",
    "name": "managed-input-424a6495",
    "description": "",
    "app_id": "uncanny-rodent",
    "run_id": "latest-fDy89wEvR",
    "upload_id": "",
    "format": {
      "input": {
        "type": "json"
      }
    },
    "created_at": "2026-07-29T14:30:34.811089656Z",
    "updated_at": "2026-07-29T14:30:34.811089656Z"
  }
]

Only the first 3 items are shown above for a cleaner display.

Update a managed input¶

You can update attributes of a managed input with the PUT /v1/applications/{application_id}/inputs/{input_id} endpoint, such as its:

Name
Description

Go the reference section to see all the available parameters for updating a managed input. You cannot update the ID or actual input data. If you need to change the data, you must create a new managed input.

The snippet below does this in three steps: it sends a GET request to fetch the current managed input, uses jq to merge the name and description fields into that response, and pipes the merged payload to a PUT request that updates the managed input.

BashOutput

curl -s -X GET "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs/baxter-burrow" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
  | jq '. + {
      "name": "This is an updated burrow for the Baxter managed input",
      "description": "A brand new description for the Baxter managed input"
    }' \
  | curl -s -X PUT "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs/baxter-burrow" \
      -H "Authorization: Bearer ${NEXTMV_API_KEY}" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq 'del(.download_url)'

{
  "id": "baxter-burrow",
  "name": "This is an updated burrow for the Baxter managed input",
  "description": "A brand new description for the Baxter managed input",
  "app_id": "uncanny-rodent",
  "run_id": "",
  "upload_id": "68ba4714-0b3b-4881-8a66-e9c104e7faa7",
  "format": {
    "input": {
      "type": "json"
    }
  },
  "created_at": "2026-07-29T14:31:20.615973444Z",
  "updated_at": "2026-07-29T14:32:17.354066886Z"
}

Delete a managed input¶

Warning

Deleting a managed input is irreversible. All the information associated with the managed input will be permanently deleted.

Delete a managed input using the DELETE /v1/applications/{application_id}/inputs/{input_id} endpoint.

Bash

curl -s -X DELETE "https://api.cloud.nextmv.io/v1/applications/uncanny-rodent/inputs/baxter-burrow" \
  -H "Authorization: Bearer ${NEXTMV_API_KEY}"