manage_doc_block
Manage document blocks in Feishu: create, update, delete blocks including tables, images, files, and generic content.
Instructions
[Official API] Manage content blocks in a document. Single tool replaces v1.3.6 create_doc_block / update_doc_block / delete_doc_blocks.
action=create — six modes (pass exactly ONE):
(A) Generic — pass children array (e.g. [{block_type:2, text:{...}}]).
(B) Image from local file — pass image_path; plugin uploads and patches.
(C) Image from token — pass image_token (already uploaded).
(D) File attachment from local file — pass file_path; plugin handles VIEW-wrap + replace_file.
(E) File from token — pass file_token.
(F) Table — pass table={rows,columns,cells?}; plugin creates a block_type=31 table (Feishu auto-makes the block_type=32 cells) and fills each provided cell. USE THIS for tables — do NOT hand-build table blocks via children (the table block_type is 31, NOT 40; getting it wrong returns invalid_param).
action=update — generic (pass update_body), image-replace (pass image_token), or file-replace (pass file_token). ⚠ update_text_elements REPLACES the block's ENTIRE elements array — it is a full overwrite, NOT a patch/append. Any element you omit (bold runs, links, prefixes) is permanently lost; to change part of a block, read it first (get_doc_blocks) and resend ALL elements.
action=delete — pass parent_block_id + start_index + end_index (range delete).
document_id accepts native ID, wiki node token, or Feishu URL.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Insert position for create (optional, appends to end if omitted). | |
| table | No | Create a table — create mode F (mutually exclusive with other create modes). Shape: {rows:int>=1, columns:int>=1, cells?:string[][] (row-major plain text; omit/empty-string to leave a cell blank), column_width?:int[] (px, length=columns), header_row?:bool, header_column?:bool}. The plugin creates a block_type=31 table, lets Feishu auto-create the cells, and fills each provided cell by updating its text — you never specify block types. Returns {tableBlockId, cells:[[cellId,...]] (row-major grid), filled, failedCells?}. Cell fills auto-retry transient Feishu errors with backoff; cells that still fail do NOT abort the call — they are listed in failedCells:[{row,col,cellId,textBlockId?,reason,skipped?}] (0-based row/col) so you can repair each via action=update on its textBlockId (or action=create into its cellId). Example: {"rows":2,"columns":2,"cells":[["Name","Role"],["Ann","PM"]]}. | |
| action | Yes | Operation to perform | |
| block_id | No | Block ID — required for action=update. | |
| children | No | Generic blocks for create mode A. E.g. [{block_type:2, text:{elements:[{text_run:{content:"Hello"}}]}}] | |
| end_index | No | Range end (exclusive) — required for delete. | |
| file_path | No | Local file path — create mode D (mutually exclusive with other create modes). | |
| file_token | No | Pre-uploaded docx file token — create mode E, or update file-replace. | |
| image_path | No | Local image path — create mode B (mutually exclusive with other create modes). | |
| document_id | Yes | Document ID, wiki node token, or Feishu URL (required for all actions) | |
| image_token | No | Pre-uploaded docx image token — create mode C, or update image-replace. | |
| start_index | No | Range start (inclusive) — required for delete. | |
| update_body | No | Generic update payload for action=update. E.g. {update_text_elements:{elements:[{text_run:{content:"new text"}}]}}. ⚠ update_text_elements is a FULL REPLACEMENT of the block's elements array (not patch/append) — include every element you want to keep, or the omitted ones are permanently lost. | |
| parent_block_id | No | Parent block ID — required for create/delete (use document_id for the doc root). |