Update an HTML block
update_blockIdempotent
Update an existing HTML block by UUID with partial field changes, preserving omitted data bindings. Preview the exact write with dry_run before committing.
Instructions
Update an existing HTML block by UUID. Only the fields you pass change — the server merges them over the current record, so an omitted ui_queries keeps the existing data binding. Authoring rules validate only your delta; violations the stored block already has are grandfathered to warnings, never blockers. dry_run:true previews the exact write.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | New CSS. | |
| data | No | Legacy query-config object — ignored by current portals; use ui_queries. | |
| name | No | New display name. | |
| tags | No | Tag list — replaces existing tags, unless merge_tags:true (then these are added). | |
| type | No | Block type. This server only handles HTML blocks, so it must be "html". | html |
| access | No | New access control object. | |
| dry_run | No | Run every gate and report the would-be write without updating. | |
| block_id | Yes | Block UUID to update. | |
| css_file | No | Path to a file holding the block's CSS; the server reads it into `css`. Same byte-exact guarantee and same root containment as html_file. Mutually exclusive with `css`. | |
| html_file | No | Path to a file holding the block's HTML+JS; the server reads it into json_data.html. PREFER THIS over inlining large content: the bytes are read off disk byte-exact, so nothing is retyped and characters like em dashes or box-drawing cannot silently normalize. Mutually exclusive with json_data.html. Must resolve under the CWD, the VC dir, or a PORTAL_FILE_ROOTS entry. | |
| json_data | No | New widget/extra config. | |
| merge_tags | No | Merge `tags` into the block's existing tags instead of replacing them — preserves functional tags (e.g. a nav 'Menu' tag). Default false. | |
| ui_queries | No | Replacement query/datasource binding. Omit to keep the block's existing binding (it is preserved automatically); pass [] to explicitly unbind all queries. | |
| expected_updated_at | No | Optimistic-concurrency token: the block's updated_at from your read. Refuses with a conflict if the block changed in between — re-read, re-apply, retry. |