Add Surface Element
add_surface_elementAdd shapes, connectors, text, or groups to the AFFiNE edgeless canvas to build diagrams programmatically. Supports styling and ignoring inapplicable fields.
Instructions
Add a shape, connector, text, or group to the AFFiNE edgeless canvas surface. Shapes support rect/ellipse/diamond/triangle with fill, stroke, and text. Connectors draw arrows between shapes (by id) or between absolute points. Use for building diagrams programmatically. Style fields that don't apply to the chosen element type are reported in the response 'ignored' list (mirrors update_surface_element).
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. | |
| type | Yes | Element type | |
| 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. | |
| 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. |