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.
Register a product installation in the given project or folder without running an installation job or installing product resources. Returns the created installation with its current Compass metadata and no latest target version. A subsequent installation job selects the version to install.
This operation is not idempotent. Repeated requests create separate installations unless the selected product version's singleton policy prohibits another installation in the destination namespace, in which case SingletonMarketplaceInstallationAlreadyExists is returned.
Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:v3:marketplace-installation:write:create.
objectstringoptionalAn optional suffix appended to the product title to form the initial display name, for example "Product title - CI staging". If omitted, the display name uses the product title alone.
stringstringoptionalThe ontology where jobs for this installation create or update ontology resources. Omit if the product does not interact with the ontology.
stringThe RID of the Compass project or folder that currently contains the installation. On creation, this is the destination where the installation is registered and its jobs create resources.
stringunionoptionalIf provided:
If not provided, the latest released version of the product is used to resolve information for the steps above.
objectA registered product installation and Compass resource. Its latest target version is absent until an installation job runs.
stringoptionalThe current description of the installation in Compass. Absent if no description is set.
stringThe current display name of the installation in Compass.
objectoptionalThe product version targeted by the latest submitted installation job. This may differ from the currently installed version. Absent if no installation job has run.
stringstringThe RID of the namespace that the installation currently belongs to in Compass.
stringoptionalThe ontology where jobs for this installation create or update ontology resources. Omit if the product does not interact with the ontology.
stringThe RID of the Compass project or folder that currently contains the installation. On creation, this is the destination where the installation is registered and its jobs create resources.
stringstring1
2
3
4
5
curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
"https://$HOSTNAME/api/v3/platform/marketplaceInstallations?preview=true" \
-d '{"parentFolderRid":"ri.compass.main.folder.0e77e9f7-683b-4e70-90b5-e35609d37864","marketplaceRid":"ri.marketplace.main.local.e74f7e10-08b7-4ed6-aad8-2ffbe901b115","productId":"4d9a2e36-52c7-49be-8d10-1fb0cc7481a2","ontologyRid":"ri.ontology.main.ontology.c1e96527-1a20-4c7b-b17a-b3c7cfc8f024","installationSuffix":"my suffix","targetVersionHint":{"versionId":"7a6f2c81-38b5-4e6d-a294-3f85d069b7c0","type":"versionId"}}'1
2
3
4
5
6
7
8
9
{
"rid": "ri.marketplace.main.block-set-installation.5b2d8f31-6c42-4a7e-9a13-8e0a3e6d9c52",
"displayName": "Example Product",
"parentFolderRid": "ri.compass.main.folder.0e77e9f7-683b-4e70-90b5-e35609d37864",
"namespaceRid": "ri.compass.main.namespace.8d34f8ce-1c38-4ff5-8b0e-01aa8d69d28c",
"marketplaceRid": "ri.marketplace.main.local.e74f7e10-08b7-4ed6-aad8-2ffbe901b115",
"productId": "4d9a2e36-52c7-49be-8d10-1fb0cc7481a2",
"ontologyRid": "ri.ontology.main.ontology.c1e96527-1a20-4c7b-b17a-b3c7cfc8f024"
}| Error Name | ||
|---|---|---|
Marketplace | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The product could not be found in the specified marketplace or has no released version available for registration. | |
| Parameters | marketplaceRid, productId | |
Singleton | Error Code | CONFLICT |
| Status Code | 409 | |
| Description | Another installation of this product already exists in the destination namespace, and the product version used for registration requires a single installation per namespace. | |
| Parameters | productId, namespaceRid | |
Parent | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The destination project or folder could not be found. | |
| Parameters | parentFolderRid | |
Marketplace | Error Code | NOT_FOUND |
| Status Code | 404 | |
| Description | The hinted product version could not be found in the specified product and marketplace. | |
| Parameters | marketplaceRid, productId, targetVersionHint | |
Create | Error Code | PERMISSION_DENIED |
| Status Code | 403 | |
| Description | Could not register the installation due to insufficient permissions on the marketplace, product, or destination project or folder. | |
| Parameters | marketplaceRid, productId, parentFolderRid | |
Invalid | Error Code | INVALID_ARGUMENT |
| Status Code | 400 | |
| Description | The semantic version in the hint must be an exact major.minor.patch version with non-negative integer components and no leading zeros. Version ranges, wildcards, prerelease identifiers, and build metadata are not supported. | |
| Parameters | targetVersionHint | |
See Errors for a general overview of errors in the platform.