Configuration is defined using profiles in Nextmv Cloud. Profiles let you define a configuration once for settings that are consistent across runs, and use it within a run by referencing the profile identifier. For certain types of functionality you'll need to define a profile in order to be able to use the feature. For example, some integration profiles require you to specify a secret API key that you wouldn't necessarily want to provide repeatedly. With a profile, you can set it once so we can store and manage the key securely.
We support two types of profiles: run profiles and integration profiles.
A run profile lets you configure information that impacts the behavior of a run.
An integration profile lets you configure information used for a partner integration.
Note, integrations and run profiles can also be set up and edited through the Nextmv Cloud Console. See the console configuration page for more information.
Endpoints
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>
Create a new run profile.
Create a new run profile that can be used when executing runs using the `v0/run` endpoint. A run profile is used to configure options that do not vary run to run. Different run profiles may be created to fulfill distinct run configurations. A run profile uses one or more third-party integrations for enhanced functionality such as using traffic data.
List all run profiles.
List the existing run profiles.
Get a specific run profile.
Fetch a specific run profile.
Modify a run profile.
Modify an existing run profile.
Delete a run profile.
Delete an existing run profile.
List all third-party run profile integrations.
List the existing third-party integrations that can be used with a run profile. Integrations enhance the functionality of the Nextmv Cloud API.
For the full specification, please visit the Nextmv Cloud API OpenAPI specification.
Using configurations
- Get the Nextmv and integration API keys (if applicable). This only needs to be done once.
- Set up an integration (if applicable). Integration profiles let you configure and securely store information used for a partner integration, such as the API key for the integrated system. See the Integrations section for a list of third-party integrations supported by Nextmv Cloud API and API endpoints for each. Note: To use an integration, it must always be configured as part of a run profile.
- Create a run profile (referencing the integration profile, if applicable).
- Use the run profile ID in the input schema when submitting a new run.
- Manage your configurations using the endpoints.
Run profiles
To use third-party integrations as part of a run, they must be referenced in a run profile. First configure the integrations and then create or update a run profile with your integration(s).
Run profiles let you configure information that impacts the behavior of a run but does not vary run to run, for example the type of measure used. A run profile optionally contains references to zero or more integration profiles. To create a run profile, send a request to the POST /v1/routing/profiles/run endpoint with a JSON payload that follows this schema:
| Property | Required | Field name | Type | Description | Example |
|---|---|---|---|---|---|
| Name | Yes | name | string | Human-readable name to identify the run profile. | "name": "Sample run profile" |
| ID | Yes | id | string | ID of the run profile; only lower case letters, numbers, and dashes permitted; max length 32 characters. | "id": "onfleet-run-profile" |
| Description | No | description | string | A description of the run profile. | "description": "Delivery profile" |
| Integrations | No | integrations | array of object | List of previously configured integrations you want to make available for the run profile. Please see: supported integrations. | "integrations": [{ "id": "onfleet-key", "type": "onfleet" }] |
Each integration object follows this schema:
| Property | Required | Field name | Type | Description | Example |
|---|---|---|---|---|---|
| Type | Yes | type | string | Type of integration. Please see: supported integrations. | "type": "onfleet" |
| ID | Yes | id | string | ID of a previously configured integration. | "id": "my-onfleet-integration" |
A sample schema and response are provided below:
Make sure to store the id, as you will need it when creating a new run. Please note that you may set up multiple run profiles using this method. You only need to do this process once for each API key.
To modify an existing run profile, you can use the PUT /v1/routing/profiles/run/{profile_id} endpoint with a JSON payload that follows the same schema as when creating a new run profile (described in the table above). Note that you may not modify the original id.