Skip to main content

Update building block

PUT 
/api/meshobjects/meshbuildingblocks/:uuid

Updates the building block and triggers an apply run on a real provisioning change (an actual input change, or a version upgrade); a no-op PUT and a displayName-only rename do not trigger a run. The dry-run variant lives on POST /{buildingBlock}/trigger-run. spec.inputs and spec.buildingBlockDefinitionVersionRef.uuid may be changed. When buildingBlockDefinitionVersionRef.uuid differs from the current version, an in-place upgrade is performed: provided inputs and spec.parentBuildingBlockRefs are applied, with existing values as fallback for inputs not supplied. The new version's required parent definitions must be satisfied by spec.parentBuildingBlockRefs; a 400 is returned if they are not, or if a newly assigned parent Building Block is being deleted. An upgrade may only move to the latest released version of the same definition; downgrades and non-released versions are rejected with a 400. As an exception, a platform operator or admin may upgrade a building block that lives in the definition's own workspace to a draft version, to test an unreleased version on a test building block before releasing it. Changing the version requires admin rights or the definition owner's permission to manage its building blocks; a workspace-scoped consumer that attempts it gets a 403. displayName can be changed in place to rename a building block on a same-version or version-change PUT; a rename alone does not trigger a run. On a same-version PUT, targetRef remains immutable, and the parent Building Blocks may change only while status.basedOnDraftVersion is true. Every added parent must be of a definition that the version lists as a dependency. Such a change requires platform operator or admin permission, is rejected with 409 while the building block is busy with a run, and triggers one apply run together with any input change. On a released version, the parent Building Blocks change through a version upgrade only. Only inputs with assignment type CUSTOMER_INPUT or PLATFORM_OPERATOR_MANUAL_INPUT can be updated. Inputs with assignment type STATIC are rejected. Null input values: for a required input, a present-but-null value is treated as 'omit this key': the existing stored value is preserved and no error is returned, and such an input cannot be cleared to null via PUT. This enables read-modify-write patterns where callers echo a full GET response body (which may contain null-valued inputs for not-yet-set inputs) without having to filter out null entries. For an input the definition marks isOptional, null is instead applied as a value: it records that the owner chose to supply none, and the implementation falls back to the default declared in its own code. Echoing a GET body back therefore remains idempotent. Note that the building block definition may be owned by a different workspace than the one owning the building block itself. API keys with workspace-scoped permissions (e.g. 'Manage Building Blocks for owned definition') can update building blocks created from definitions owned by that workspace, even if the building block resides on a tenant in another workspace. The type of a value you send back unchanged is not checked again. For a sensitive input, value may carry hash to keep the existing secret unchanged, e.g. { "hash": "sha256:<hexdigest>" }. If the hash does not match the stored hash, the request fails with 409 Conflict (drift detected). Do not provide both plaintext and hash. The response shows the Building Block before the run that this request triggers has started. To wait for that run, see Waiting for a Run.

Request​

Responses​

Building block updated