> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Block
> Update a block with partial data.
Only the provided fields are updated. This enables targeted updates
like position changes without affecting other block properties.
Patch a block with partial data. Only the fields you supply are touched; everything else is left as-is.
Common reasons to call this:
* **Reposition** on the canvas — `position_x` / `position_y` / `width` / `height`
* **Rename** the block — `label`
* **Reconfigure** the block — `config` (replaces the existing config; merge it client-side first if you want a partial change)
* **Reparent** into or out of a container — `parent_id`
`type` is intentionally not patchable. To change a block's type, delete it and create a new one with the same `id`.
```python Python theme={null}
from retab import Retab
client = Retab()
# Move + rename
block = client.workflows.blocks.update(
block_id="extract-1",
label="Extract Invoice Fields v2",
position_x=480,
position_y=160,
)
# Replace the config (e.g. tighten the schema, switch model)
block = client.workflows.blocks.update(
block_id="extract-1",
config={
"model": "gpt-5-mini",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
"vendor": {
"type": "object",
"properties": {"name": {"type": "string"}}
}
},
},
},
)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const block = await client.workflows.blocks.update("extract-1", "Extract Invoice Fields v2", 480, 160);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
label := "Extract Invoice Fields v2"
positionX := 480.0
positionY := 160.0
block, err := client.Workflows.Blocks.Update(ctx, "extract-1", &retab.WorkflowBlocksUpdateParams{
Label: &label,
PositionX: &positionX,
PositionY: &positionY,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(block.ID, block.Label)
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
block = client.workflows.blocks.update(
block_id: 'extract-1',
label: 'Extract Invoice Fields v2',
position_x: 480,
position_y: 160,
)
puts "#{block.id} #{block.label}"
```
```rust Rust theme={null}
use retab::models::UpdateWorkflowBlockRequest;
use retab::resources::workflow_blocks::UpdateParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let block = client
.workflows().blocks()
.update(
"extract-1",
UpdateParams::new(UpdateWorkflowBlockRequest {
label: Some("Extract Invoice Fields v2".into()),
position_x: Some(480.0),
position_y: Some(160.0),
..Default::default()
}),
)
.await?;
println!("{} {}", block.id, block.label.as_deref().unwrap_or(""));
Ok(())
}
```
```php PHP theme={null}
workflows()->blocks()->update(
blockId: 'blk_extract_1',
);
print_r($result);
```
```csharp C# theme={null}
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Workflows.Blocks.UpdateAsync("blk_extract_1", new WorkflowBlocksUpdateOptions());
Console.WriteLine(result);
```
```java Java theme={null}
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.workflows().blocks().update("block_abc123", "wf_abc123", null, null, null, null, null, null, null, null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'PATCH' \
'https://api.retab.com/v1/workflows/blocks/extract-1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"label": "Extract Invoice Fields v2",
"position_x": 480,
"position_y": 160
}'
```
```json 200 theme={null}
{
"id": "extract-1",
"workflow_id": "wf_abc123xyz",
"type": "extract",
"label": "Extract Invoice Fields v2",
"position_x": 480,
"position_y": 160,
"width": null,
"height": null,
"config": {
"model": "gpt-5",
"json_schema": {
"type": "object",
"properties": { "total": { "type": "number" } }
}
},
"parent_id": null,
"updated_at": "2026-05-01T14:30:00Z"
}
```
```json 404 theme={null}
{
"detail": "Block not found"
}
```
## OpenAPI
````yaml PATCH /v1/workflows/blocks/{block_id}
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/blocks/{block_id}:
patch:
tags:
- Workflows
- Workflow Blocks
summary: Update Block
description: |-
Update a block with partial data.
Only the provided fields are updated. This enables targeted updates
like position changes without affecting other block properties.
operationId: update_block
parameters:
- in: path
name: block_id
required: true
schema:
type: string
title: Block Id
- in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Disambiguates a block id that is shared by more than one workflow.
Required only when the block id is not unique within your
organization.
title: Workflow Id
required: false
description: >-
Disambiguates a block id that is shared by more than one workflow.
Required only when the block id is not unique within your
organization.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkflowBlockRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowBlock'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
UpdateWorkflowBlockRequest:
properties:
label:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Label
position_x:
anyOf:
- type: number
- type: 'null'
title: Position X
position_y:
anyOf:
- type: number
- type: 'null'
title: Position Y
width:
anyOf:
- type: number
- type: 'null'
title: Width
height:
anyOf:
- type: number
- type: 'null'
title: Height
config:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Config
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
config_mode:
anyOf:
- type: string
enum:
- merge
- replace
- type: 'null'
title: Config Mode
description: >-
How to apply the `config` field. 'merge' (default) deep-merges the
patch into the existing config with null-as-delete; 'replace' uses
the patch as the full new config.
type: object
title: UpdateWorkflowBlockRequest
description: |-
Update a block. Only the fields you provide are changed.
`config_mode` controls how `config` is applied:
* `"merge"` (default): the given `config` is merged into the existing
one — nested objects are combined, and a `null` value deletes a key.
* `"replace"`: the given `config` replaces the existing one entirely.
WorkflowBlock:
properties:
id:
type: string
title: Id
workflow_id:
type: string
title: Workflow Id
description: Foreign key to workflow
type:
type: string
enum:
- start_document
- start_json
- note
- parse
- edit
- extract
- split
- classifier
- conditional
- api_call
- function
- while_loop
- for_each
- merge_dicts
- while_loop_sentinel_start
- while_loop_sentinel_end
- for_each_sentinel_start
- for_each_sentinel_end
title: Type
description: Block type (extract, parse, classifier, etc.)
label:
type: string
title: Label
description: Display label for the block
default: ''
position_x:
type: number
title: Position X
description: X position on canvas
default: 0
position_y:
type: number
title: Position Y
description: Y position on canvas
default: 0
width:
anyOf:
- type: number
- type: 'null'
title: Width
description: Block width for resizable blocks
height:
anyOf:
- type: number
- type: 'null'
title: Height
description: Block height for resizable blocks
config:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Config
description: Block-specific configuration
parent_id:
anyOf:
- type: string
- type: 'null'
title: Parent Id
description: ID of parent container (while_loop, for_each)
declarative_path:
anyOf:
- type: string
- type: 'null'
title: Declarative Path
description: Canonical declarative block path used to reconcile imported specs.
declarative_source_block_id:
anyOf:
- type: string
- type: 'null'
title: Declarative Source Block Id
description: Authored declarative block id before import-time id regeneration.
updated_at:
type: string
format: date-time
title: Updated At
resolved_schemas:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Resolved Schemas
description: Schemas resolved for this block from the workflow graph.
type: object
required:
- id
- type
- updated_at
- workflow_id
title: WorkflowBlock
description: Public live workflow block object.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````