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:

import json, urllib.request

def get_feishu_token():
    with open(os.path.expanduser("~/.openclaw/openclaw.json")) as f:
        c = json.load(f)["channels"]["feishu"]
    payload = json.dumps({"app_id": c["appId"], "app_secret": c["appSecret"]}).encode()
    req = urllib.request.Request(
        "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
        data=payload, headers={"Content-Type": "application/json"}, method="POST")
    return json.loads(urllib.request.urlopen(req).read())["tenant_access_token"]

All API calls use header: Authorization: Bearer {token}

Rate Limits

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

API Reference

Base URL: https://open.feishu.cn/open-apis/docx/v1/documents

1. Get Block

GET /docx/v1/documents/{doc}/blocks/{block_id}

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

2. Get Children (with optional full tree)

GET /docx/v1/documents/{doc}/blocks/{block_id}/children
    ?with_descendants=true    # get ALL descendants, not just direct children
    &page_size=500            # max 500
    &document_revision_id=-1  # latest revision

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

3. Create Blocks (simple, flat only)

POST /docx/v1/documents/{doc}/blocks/{parent_id}/children
Body: {"children": [...blocks], "index": 0}

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

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

POST /docx/v1/documents/{doc}/blocks/{parent_id}/descendant
Body: {
    "children_id": ["temp_id_1", "temp_id_2"],
    "descendants": [...all_blocks_with_parent_child_relations],
    "index": 0
}