Upgrade preview products

POST/api/v1/products/upgrade-preview

Authorization
Permission	`products.install`
Workspace scope	required
Scope target	workspace

Request body

Request body fields
Field	Type	Required	Nullable	Default
installationId	string	required	non-null	—
targetVersion	string	required	non-null	—
expectedCurrentPlan	object	optional	non-null	—
expectedCurrentPlan.planSchemaVersion	number	required	non-null	—
expectedCurrentPlan.planHash	string	required	non-null	—
expectedTargetPlan	object	optional	non-null	—
expectedTargetPlan.planSchemaVersion	number	required	non-null	—
expectedTargetPlan.planHash	string	required	non-null	—
expectedInstallUpdatedAt	string	required	non-null	—
expectedManifestDigest	string	required	non-null	—
expectedConfigurationRevision	string	required	non-null	—
bindings	object	optional	non-null	—
productConfig	object	optional	non-null	—

Response

201

Response fields
Field	Type	Required	Nullable	Default
data	object	required	non-null	—
data.disposition	"ready" \| "requires_resolution"	required	non-null	—
data.baseline	unknown	required	non-null	—
data.plan	object	required	non-null	—
data.plan.schemaVersion	number	required	non-null	—
data.plan.root	object	required	non-null	—
data.plan.root.productKey	string	required	non-null	—
data.plan.root.productVersion	string	required	non-null	—
data.plan.root.manifestDigest	string	required	non-null	—
data.plan.graph	array	required	non-null	—
data.plan.references	array	required	non-null	—
data.plan.ownedContentOrder	array	required	non-null	—
data.plan.planHash	string	required	non-null	—
data.delta	unknown	required	non-null	—
data.staleGuard	object	required	non-null	—
data.staleGuard.current	object	required	non-null	—
data.staleGuard.current.planSchemaVersion	number	required	non-null	—
data.staleGuard.current.planHash	string	required	non-null	—
data.staleGuard.target	object	required	non-null	—
data.staleGuard.target.planSchemaVersion	number	required	non-null	—
data.staleGuard.target.planHash	string	required	non-null	—
data.staleGuard.currentManifestDigest	string	required	non-null	—
data.staleGuard.currentInstallUpdatedAt	string	required	non-null	—
data.staleGuard.currentConfigurationRevision	string	required	non-null	—
data.targetInputs	object	required	non-null	—
data.targetInputs.bindings	object	required	non-null	—
data.targetInputs.roleSatisfactions	object	optional	non-null	—
data.targetInputs.productConfig	object	optional	non-null	—
data.targetInputs.configurationProjectionDigest	string	optional	non-null	—
data.targetInputs.profile	object	optional	non-null	—
data.targetInputs.profile.profileKey	string	required	non-null	—
data.targetInputs.profile.profileVersion	string	required	non-null	—
data.targetInputs.profile.profileDigest	string	required	non-null	—
data.targetInputs.configurationResolution	object	optional	non-null	—
data.targetInputs.configurationResolution.settings	object	required	non-null	—
data.targetInputs.configurationResolution.bindings	object	required	non-null	—
data.targetInputs.configurationResolution.roleSatisfactions	object	optional	non-null	—
data.targetInputs.configurationResolution.inputSlotSatisfactions	object	required	non-null	—
data.targetInputs.configurationResolution.planHash	string	required	non-null	—
data.targetInputs.referenceInputs	object	optional	non-null	—
data.blockers	array	required	non-null	—

Declared failures

Declared failures
PRODUCT_OPERATION_FAILED	500 — not retryable
PRODUCT_REQUIRES_RESOLUTION	409 — not retryable
PRODUCT_STALE	409 — not retryable

Readback

This method returns the current state it read.

products.upgradePreview

Request example

Schematic only. Replace placeholders with real values and include all required nested fields.

POST /api/v1/products/upgrade-preview HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json

{
  "installationId": "<installationId>",
  "targetVersion": "<targetVersion>",
  "expectedInstallUpdatedAt": "<expectedInstallUpdatedAt>",
  "expectedManifestDigest": "<expectedManifestDigest>",
  "expectedConfigurationRevision": "<expectedConfigurationRevision>"
}