Feishu Block Operations

Direct REST API operations for Feishu cloud documents when the feishu_doc tool's built-in actions don't cover your needs.

When to Use This (vs feishu_doc)

Authentication

Get tenant access token from OpenClaw config:

CODEBLOCK0

All API calls use header: INLINECODE8

Rate Limits

Use time.sleep(0.35) between write calls. For reads, time.sleep(0.25).

API Reference

Base URL: INLINECODE11

1. Get Block

CODEBLOCK1

Returns single block with full content (type, elements, children IDs, styles).

2. Get Children (with optional full tree)

CODEBLOCK2

Tip: Use with_descendants=true on table blocks to get all cells + cell content in one call.

3. Create Blocks (simple, flat only)

CODEBLOCK3

• - Max 50 blocks per call
• Cannot create nested structures (e.g. table with cell content)
• INLINECODE13 in body: 0=beginning, -1=end (default)

4. Create Nested Blocks (tables, grids, etc.)

CODEBLOCK4

• - Max 1000 blocks per call
• INLINECODE14: only first-level child IDs (NOT grandchildren — causes error 1770006)
• INLINECODE15: flat array of ALL blocks including nested ones, each with block_id, block_type, children (list of child temp IDs)
• ⚠️ index MUST be in request body, NOT as URL query parameter — ?index=N is silently ignored

5. Batch Update Blocks

CODEBLOCK5

Max 200 blocks per call. Each request object contains block_id + one operation:

Example: batch update text in multiple cells

CODEBLOCK6

6. Update Single Block

CODEBLOCK7

7. Delete Blocks

CODEBLOCK8

• - ⚠️ Uses start_index/end_index (half-open interval [start, end)), NOT INLINECODE35
• Indices are relative to the parent block's children list

Block Types

Text Elements

Text blocks contain an elements array. Each element is one of:

CODEBLOCK9

Common Patterns

Pattern 1: Read table content

CODEBLOCK10

Pattern 2: Insert Markdown at position

Use feishu-md2blocks skill's md2blocks.py script with --after <block_id>.

Or manually:
CODEBLOCK11

Pattern 3: Batch edit table cells

CODEBLOCK12

Pattern 4: Delete then re-insert (position workaround)

When you need to replace content at a specific position:

CODEBLOCK13

Gotchas & Lessons Learned

1. 1. /descendant index in body, not URL — The most common pitfall. ?index=N compiles but is silently ignored.
2. batch_delete uses index range — {"start_index": 0, "end_index": 5} deletes children[0..4]. Do NOT pass block_ids.
3. Table merge_info is read-only — Must strip from blocks before insertion or API returns error.
4. children_id is first-level only — Including grandchild IDs in children_id causes error 1770006.
5. Rate limit is per-document — Multiple concurrent edits to the same doc share the 3/sec limit.
6. with_descendants=true saves calls — One GET instead of N+1 for reading table content.
7. Convert API returns temp IDs — After insertion, actual block IDs differ from the temp IDs used during convert.