Version 3.0Beta

Discover Inputs Marketplace Installation Jobs

POST/api/v3/platform/marketplaceInstallationJobs/discoverInputs

Warning

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.

Discover required and optional inputs for existing installations and their proposed target versions.

Resolves input requirements and available sources using the requested target versions, location overrides, and recommendation strategies.

The request token must have permission to edit each target. Every input in the target product versions must have an API name.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:v3:marketplace-installation-job:read:discover-inputs.

Query parameters

preview

booleanoptional

Enables the use of preview functionality.

Request body

DiscoverInstallationJobInputsRequest

object

Hide child attributes

installations

list<InstallationTarget>optional

Between 1 and 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.

Show child attributes

recommendations

list<RecommendationStrategy>optional

An empty list disables recommendations from installations outside the requested targets. Targets in this request may still supply inputs to one another.

Show child attributes

sourceFilter

objectoptional

When supplied, excludes an input if any of its available sources appears in excludedSources. If omitted, returns only inputs whose sole available source is MANUAL. Inputs with no available source are always omitted.

Show child attributes

Response body

DiscoverInstallationJobInputsResponse

object

Hide child attributes

errors

list<InstallationError>optional

Errors encountered during input resolution. Errors for inputs excluded by sourceFilter are omitted.

Show child attributes

inputs

map<MarketplaceInstallationRid, DiscoveredInstallationInputs>optional

All matching input requirements for each requested installation after source filtering, without pagination. An installation's input map is empty if no inputs match.

Show child attributes

Examples

Request

Copied!

curl -X POST \
\t-H "Content-type: application/json" \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v3/platform/marketplaceInstallationJobs/discoverInputs?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"}}}],"recommendations":[{"suffixFilter":"shared","type":"sameNamespace"}],"sourceFilter":{"excludedSources":["AUTO_MAPPED"]}}'

Response

Copied!

{
  "inputs": {
    "ri.marketplace.main.block-set-installation.5b2d8f31-6c42-4a7e-9a13-8e0a3e6d9c52": {
      "inputs": {
        "myDataset.address": {
          "inputId": "0c47d2a9-83e1-4f6b-9d50-2a8b74e3c619",
          "inputType": "DATA_SOURCE_COLUMN",
          "optional": false,
          "sources": [
            "MANUAL"
          ],
          "supportedTypes": [
            {
              "valueType": "STRING",
              "type": "simple"
            }
          ]
        }
      }
    }
  },
  "errors": [
    {
      "severity": "BLOCKING",
      "target": {
        "type": "job"
      },
      "errorValue": {
        "errorCode": "INVALID_ARGUMENT",
        "errorName": "Marketplace:IncompatibleDefaultBuildOptions",
        "parameters": {
          "errorType": {
            "kind": "installJob"
          }
        },
        "type": "other"
      }
    }
  ]
}

Error responses

Error Name
`InstallationUninstallStarted`	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`
`AmbiguousInstallationRecommendation`	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`
`ConflictingInstallationRecommendation`	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`
`DiscoverInstallationJobInputsPermissionDenied`	Error Code	`PERMISSION_DENIED`
	Status Code	403
	Description	The request token does not have permission to edit one or more target installations and cannot discover their inputs.
	Parameters	`installationRids`
`DuplicateInstallationJobInstallations`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	An installation occurs more than once in the target list.
	Parameters	`installationRids`
`InstallationTargetVersionNotFound`	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`
`InstallationInputApiNamesNotEnabled`	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`
`MarketplaceInstallationNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description
	Parameters	`marketplaceInstallationRid`
`InstallationJobMarketplaceConstraintViolated`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The target products must belong to a single marketplace.
	Parameters	`installationRids`
`MissingInstallationJobInstallations`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	At least one installation target must be supplied.
	Parameters
`InstallationJobNamespaceConstraintViolated`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The target installations must belong to a single namespace.
	Parameters	`installationRids`
`InstallationDraftAlreadyExists`	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`
`DuplicateInstallationJobProducts`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	More than one target installation uses the same product.
	Parameters	`productId, installationRids`
`MaxInstallationJobInstallationsCountExceeded`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The number of installation targets exceeds the maximum supported by this operation.
	Parameters	`installationsCount, maxInstallationsCount`
`InstallationJobOntologyConstraintViolated`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The target installations must have at most one resulting ontology after applying location overrides.
	Parameters	`installationRids`
`DiscoverInstallationJobInputsFailed`	Error Code	`INTERNAL`
	Status Code	500
	Description	Marketplace could not complete input discovery.
	Parameters	`errorName, errorCode`
`InvalidInstallationTargetVersion`	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.