Update Surface Element
update_surface_elementPartially update a surface element's properties (position, size, text, style) by ID. Merges x/y/width/height; replaces text/label/title; reports non-applicable fields.
Instructions
Partially update a surface element by id. x/y/width/height merge with the element's current xywh (move without resizing, or vice versa). text/label/title replace their Y.Text wholesale. Fields that don't apply to the element's type are reported in the response 'ignored' list.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X position on canvas (shape/text; default 0). | |
| y | No | Y position on canvas (shape/text; default 0). | |
| mode | No | Connector mode: 0=straight, 1=orthogonal (elbow), 2=curve (default 2). Connector only. | |
| text | No | Text content (shape/text) or connector label. Replaces existing Y.Text on update. | |
| color | No | Text color. Shape default `#000000` — keep unless the fill is dark, then pass a contrasting hex. Canvas text default `--affine-text-primary-color` (theme-adaptive). Shape/text. | |
| docId | Yes | Document ID | |
| index | No | BlockSuite fractional-index string controlling z-order. On add, defaults to a key above every existing element's index (new elements render on top). On update, replaces the stored value — pass a key less than some existing index to send-to-back, or greater to bring-to-front. Use the value returned by list_surface_elements to pick a specific position. | |
| label | No | Connector label (stored as text on the connector). Connector only. | |
| title | No | Group title. Group only. | |
| width | No | Width (shape default 100, text default 200). | |
| filled | No | Whether shape is filled (default true). Shape only. | |
| height | No | Height (shape default 100, text default 30). | |
| radius | No | Corner radius for rect (0.1 = rounded). Shape only. | |
| stroke | No | Connector stroke color (default '--affine-text-primary-color' — theme-adaptive, near-black in light / near-white in dark). Accepts any CSS color or AFFiNE palette token. Connector only. | |
| children | No | Child element ids. Group only. | |
| fontSize | No | Font size (shape default 20, text default 16). Shape/text. | |
| sourceId | No | Connector source element id. Connector only. | |
| targetId | No | Connector target element id. Connector only. | |
| elementId | Yes | Element ID to update | |
| fillColor | No | Fill color. Prefer the `--affine-palette-shape-<color>` family (yellow/orange/red/magenta/purple/navy/blue/green/teal/grey/white/black). These are fixed colors — AFFiNE shape colors are not theme-adaptive by design. Shape only. | |
| shapeType | No | Shape type (default rect). Shape only. | |
| fontWeight | No | Font weight (shape default 600, text default 400). Shape/text. | |
| strokeColor | No | Stroke color. Prefer the `--affine-palette-line-<color>` family (same color names as fillColor). Fixed colors, not theme-adaptive. Shape only. | |
| strokeStyle | No | Stroke style. Shape/connector. | |
| strokeWidth | No | Stroke width (default 2). Shape/connector. | |
| workspaceId | No | Workspace ID (optional if default set) | |
| sourcePosition | No | Source [x,y]: relative [0-1] if sourceId set, absolute otherwise. Connector only. | |
| targetPosition | No | Target [x,y]: relative [0-1] if targetId set, absolute otherwise. Connector only. When both source/target are bound by id and neither position is provided, endpoints snap to the BlockSuite side-midpoint facing the other endpoint so connectors flow in a clear direction. Pass [0.5,0] top, [0.5,1] bottom, [0,0.5] left, [1,0.5] right to force a specific side. | |
| rearEndpointStyle | No | Rear endpoint style (default Arrow). Connector only. | |
| frontEndpointStyle | No | Front endpoint style (default None). Connector only. |