Upgrade apply products
POST /api/v1/products/upgrade-apply: request fields and declared response contract.
POST/api/v1/products/upgrade-apply
| Permission | products.install |
|---|---|
| Workspace scope | required |
| Scope target | workspace |
Request body
| 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 | — |
| planId | string | required | non-null | — |
| idempotencyKey | string | required | non-null | — |
Response
201
| Field | Type | Required | Nullable | Default |
|---|---|---|---|---|
| data | object | required | non-null | — |
| data.attempt | object | required | non-null | — |
| data.attempt.id | string | required | non-null | — |
| data.attempt.companyId | string | required | non-null | — |
| data.attempt.workspaceId | string | required | non-null | — |
| data.attempt.installationId | string | required | non-null | — |
| data.attempt.planId | string | required | non-null | — |
| data.attempt.attemptKey | integer | required | non-null | — |
| data.attempt.invocationKey | string | required | non-null | — |
| data.attempt.operation | "install" | "upgrade" | required | non-null | "install" |
| data.attempt.state | "running" | "succeeded" | "failed_retryable" | "failed_permanent" | "requires_resolution" | required | non-null | — |
| data.attempt.executionFence | integer | required | non-null | 0 |
| data.attempt.executionClaimId | unknown | required | non-null | — |
| data.attempt.executionClaimedAt | unknown | required | non-null | — |
| data.attempt.executionClaimExpiresAt | unknown | required | non-null | — |
| data.attempt.startedAt | unknown | required | non-null | — |
| data.attempt.completedAt | unknown | required | non-null | — |
| data.attemptState | "running" | "succeeded" | "failed_retryable" | "failed_permanent" | "requires_resolution" | required | non-null | — |
| data.installationState | "installing" | "partial" | "installed" | "requires_resolution" | "failed" | "retired" | required | non-null | — |
| data.completedUnitCount | integer | required | non-null | — |
| data.failedNodeKey | string | optional | non-null | — |
| data.failedUnitKind | "identity" | "owned_content" | optional | non-null | — |
| data.terminalReceipt | object | optional | non-null | — |
| data.preview | object | optional | non-null | — |
| data.preview.disposition | "ready" | "requires_resolution" | required | non-null | — |
| data.preview.baseline | unknown | required | non-null | — |
| data.preview.plan | object | required | non-null | — |
| data.preview.plan.schemaVersion | number | required | non-null | — |
| data.preview.plan.root | object | required | non-null | — |
| data.preview.plan.graph | array | required | non-null | — |
| data.preview.plan.references | array | required | non-null | — |
| data.preview.plan.ownedContentOrder | array | required | non-null | — |
| data.preview.plan.planHash | string | required | non-null | — |
| data.preview.delta | unknown | required | non-null | — |
| data.preview.staleGuard | object | required | non-null | — |
| data.preview.staleGuard.current | object | required | non-null | — |
| data.preview.staleGuard.target | object | required | non-null | — |
| data.preview.staleGuard.currentManifestDigest | string | required | non-null | — |
| data.preview.staleGuard.currentInstallUpdatedAt | string | required | non-null | — |
| data.preview.staleGuard.currentConfigurationRevision | string | required | non-null | — |
| data.preview.targetInputs | object | required | non-null | — |
| data.preview.targetInputs.bindings | object | required | non-null | — |
| data.preview.targetInputs.roleSatisfactions | object | optional | non-null | — |
| data.preview.targetInputs.productConfig | object | optional | non-null | — |
| data.preview.targetInputs.configurationProjectionDigest | string | optional | non-null | — |
| data.preview.targetInputs.profile | object | optional | non-null | — |
| data.preview.targetInputs.configurationResolution | object | optional | non-null | — |
| data.preview.targetInputs.referenceInputs | object | optional | non-null | — |
| data.preview.blockers | array | required | non-null | — |
Declared failures
| PRODUCT_OPERATION_FAILED | 500 — not retryable |
|---|---|
| PRODUCT_REQUIRES_RESOLUTION | 409 — not retryable |
| PRODUCT_STALE | 409 — not retryable |
Readback
Read the result back with:
- products.inspectInstalled
Request example
Schematic only. Replace placeholders with real values and include all required nested fields.
POST /api/v1/products/upgrade-apply 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>",
"planId": "<planId>",
"idempotencyKey": "<idempotencyKey>"
}