This endpoint is in preview and may be modified or removed at any time.
To use this endpoint, add preview=true to the request query parameters.
Create a job to upgrade existing installations to their target versions.
The operation returns before preparation and validation complete. Poll the job's status to track progress.
Specify 1 to 10 distinct installations, with at most one installation per product. Targets must share a namespace and marketplace and have at most one resulting ontology after applying overrides.
For each target, values and explicitlyUnset replace all previously provided values and explicit unsets.
Inputs omitted from both fields may be fulfilled by defaults, automatic mapping, or recommendations. Use
discoverInputs to inspect available sources.
This operation is not idempotent. Repeating it may create another draft or return a conflict.
Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:v3:marketplace-installation-job:write:create.
objectlist<InstallationJobTarget>optionalExisting installations to upgrade to their target versions, along with their input mappings.
list<RecommendationStrategy>optionalStrategies for selecting other installations whose outputs can fulfill the targets' inputs. Targets in this request may still supply inputs to one another, independent of recommendation strategy.
unionoptionalIf omitted, submit with NON_BLOCKING_ERRORS tolerance and ABORT handling.
objectAn attempt to upgrade one or more existing product installations. The same RID identifies the draft and its submitted job.
stringThe RID of a Marketplace installation job or its draft.
string (enum)Values:
Enum values: PREPARING, IDLE_DRAFT, ABORTING, IN_PROGRESS, BUILDING, ABORTED, SUCCEEDED, FAILED
1
2
3
4
5
curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
"https://$HOSTNAME/api/v3/platform/marketplaceInstallationJobs?preview=true" \
-d '{"installations":[{"installationRid":"ri.marketplace.main.block-set-installation.5b2d8f31-6c42-4a7e-9a13-8e0a3e6d9c52","targetVersion":{"type":"latest"},"overrides":{"ontology":{"ontologyRid":"ri.ontology.main.ontology.c1e96527-1a20-4c7b-b17a-b3c7cfc8f024","type":"set"}},"inputs":{"values":{"myDataset":{"type":"rid","rid":"ri.foundry.main.dataset.2f6d7c83-9e41-4b5a-8d20-1c7a34f0e6b9"},"myDataset.address":{"type":"string","value":"address"}},"explicitlyUnset":["myDataset.postcode"]}}],"recommendations":[{"suffixFilter":"shared","type":"sameNamespace"}],"submissionMode":{"type":"draft"}}'1
2
3
4
{
"rid": "ri.marketplace.main.installation-job.1a80ebf8-341a-4d9e-98e2-9fd4ba7c14d8",
"status": "PREPARING"
}| Error Name | ||
|---|---|---|
Installation | Error Code | CONFLICT |
| Status Code | 409 | |
| Description | Uninstall has begun for the target installation. Create a new installation to install the product again. | |
| Parameters | installationRid | |
Ambiguous | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | A namespace recommendation strategy matches multiple installations of the same linked product. Narrow its suffix filter or use explicit recommendations. Overlapping recommendation inputs or sources are reported separately as `InstallationError` entries in the discovery response. | |
| Parameters | productId, installationRids | |
Conflicting | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | A recommendation supplies a product that is also included in the requested targets. Remove that recommendation. | |
| Parameters | recommendationInstallationRid, requestedInstallationRid | |
Duplicate | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | An installation occurs more than once in the target list. | |
| Parameters | installationRids | |
Installation | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | An input API name is not present in the selected product version. | |
| Parameters | installationRid, apiName | |
Installation | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The requested target version could not be found within the installation product and marketplace. | |
| Parameters | installationRid, targetVersion | |
Installation | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | One or more installations have product inputs without API names. Enable input API name generation for those products before interacting with them. | |
| Parameters | installationRids | |
Missing | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | A child input with a value requires its parent to have a value in `inputs.values` for the same installation. | |
| Parameters | installationRid, childApiName, parentApiName | |
Create | Error Code | PERMISSION_DENIED |
| Status Code | 403 | |
| Description | The request token cannot prepare or submit a job for one or more target installations or dependencies. | |
| Parameters | installationRids | |
Marketplace | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | ||
| Parameters | marketplaceInstallationRid | |
Installation | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The target products must belong to a single marketplace. | |
| Parameters | installationRids | |
Missing | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | At least one installation target must be supplied. | |
| Parameters | | |
Installation | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The target installations must belong to a single namespace. | |
| Parameters | installationRids | |
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | An input value could not be converted for the selected product version. The error reason does not contain the supplied value. | |
| Parameters | installationRid, apiName, reason | |
Installation | Error Code | CONFLICT |
| Status Code | 409 | |
| Description | The caller already has a preparing or idle draft for a target installation. Complete or abort the existing draft before preparing another job or discovering inputs for that installation. | |
| Parameters | installationRid, existingInstallationJobRid | |
Duplicate | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | More than one target installation uses the same product. | |
| Parameters | productId, installationRids | |
Conflicting | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | An input name occurs more than once in `explicitlyUnset` or occurs in both `values` and `explicitlyUnset` for the same installation. | |
| Parameters | installationRid, apiName | |
Conflicting | Error Code | CONFLICT |
| Status Code | 409 | |
| Description | An installation targeted for submission already has a running job. Draft mode may still prepare a draft. | |
| Parameters | installationRids | |
Max | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The number of installation targets exceeds the maximum supported by this operation. | |
| Parameters | installationsCount, maxInstallationsCount | |
Installation | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The target installations must have at most one resulting ontology after applying location overrides. | |
| Parameters | installationRids | |
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The target semantic version must be an exact major.minor.patch version with non-negative integer components and no leading zeros. Each component must be at most 2⁵³ - 2 (9,007,199,254,740,990). Version ranges, wildcards, prerelease identifiers, and build metadata are not supported. | |
| Parameters | version | |
See Errors for a general overview of errors in the platform.