Append Block
append_blockAppend document blocks using canonical types and legacy aliases, with optional placement and strict validation for precise content structuring.
Instructions
Append document blocks with canonical types and legacy aliases (supports placement + strict validation).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | No | ||
| docId | Yes | ||
| type | Yes | Block type. Canonical: paragraph|heading|quote|list|code|divider|callout|latex|table|bookmark|image|attachment|embed_youtube|embed_github|embed_figma|embed_loom|embed_html|embed_linked_doc|embed_synced_doc|embed_iframe|database|data_view|surface_ref|frame|edgeless_text|note. Legacy aliases remain supported. | |
| text | No | Block content text | |
| url | No | URL for bookmark/embeds | |
| pageId | No | Target page/doc id for linked/synced doc embeds | |
| iframeUrl | No | Override iframe src for embed_iframe | |
| html | No | Raw html for embed_html | |
| design | No | Design payload for embed_html | |
| reference | No | Target id for surface_ref | |
| refFlavour | No | Target flavour for surface_ref (e.g. affine:frame) | |
| x | No | X position on the edgeless canvas for frame/edgeless_text/note (default 0). Prefer ≥40px between sibling bounds; BlockSuite does not auto-arrange. | |
| y | No | Y position on the edgeless canvas for frame/edgeless_text/note (default 0). | |
| width | No | Width for frame/edgeless_text/note. | |
| height | No | Height for frame/edgeless_text/note. When `markdown` is set and height is omitted, an over-estimate is computed from the content — AFFiNE's render-time ResizeObserver corrects `prop:xywh` to the true DOM-measured height on first browser open. | |
| background | No | Background for frame/note. Frame default 'transparent'. For notes, prefer AFFiNE's adaptive `--affine-note-background-<color>` family — `blue` / `purple` / `yellow` / `green` / `teal` / `red` / `orange` / `magenta` / `grey` / `white` / `black`. For specific per-theme colors, pass a `{light, dark}` hex object like `{light:'#fff', dark:'#252525'}`. | |
| markdown | No | When type='note', parse this markdown into heading/paragraph/list/code child blocks inside the note (BlockSuite-native: mirrors what happens when you paste markdown into an edgeless note). Takes precedence over 'text' for note children. Ignored for other block types. | |
| childElementIds | No | For type='frame' only. The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — BlockSuite's prop:childElementIds holds both, matching what the editor writes when you drag a note into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. When width/height are omitted the frame is sized to the union of resolvable child bounds + padding + a 30px title band. | |
| stackAfter | No | Layout helper — position this block relative to one or more existing edgeless blocks. Picks the furthest anchor in `direction` for the stack axis, and centers the new block on the anchor group's union on the orthogonal axis (matches how BlockSuite aligns selection-derived blocks; reduces to inherit-anchor-x when widths match). Caller-provided x/y on the orthogonal axis still wins. Works for frame/note/edgeless_text. Example: `stackAfter: { blockId: [f1, f2, f3], gap: 80 }` stacks below whichever column frame ends lowest, centered across all three. Note heights shift at first render (page-root grows with the title, content notes shrink/grow with their children); give extra gap and fix up with `update_edgeless_block` if the down/right chain drifts. | |
| padding | No | Default padding (px) for `childElementIds` auto-sizing on frames (each side, plus +30px title band) and fallback gap for `stackAfter` (default 40). | |
| sourceId | No | Blob source id for image/attachment | |
| name | No | Attachment file name | |
| mimeType | No | Attachment mime type | |
| size | No | Attachment/image file size in bytes | |
| embed | No | Attachment embed mode | |
| rows | No | Table row count | |
| columns | No | Table column count | |
| latex | No | Latex expression | |
| level | No | Heading level for type=heading | |
| style | No | List style for type=list | |
| bookmarkStyle | No | Bookmark card style | |
| viewMode | No | Initial data view preset for type=database or type=data_view. Defaults: database=table, data_view=kanban | |
| checked | No | Todo state when type is todo | |
| language | No | Code language when type is code | |
| caption | No | Code caption when type is code | |
| strict | No | Strict validation mode (default true) | |
| placement | No | Optional insertion target/position |