Feishu (Lark) Document API writing spec. Converts Markdown content to Feishu Block structures and writes to cloud docs. Handles concurrency ordering. Use when syncing articles, creating document blocks, or writing long-form content to Feishu docs.
Reference spec for writing content to Feishu (Lark) cloud documents via the Docx API. Feishu docs use a Block tree model — raw Markdown is not accepted.
CODEBLOCK0
Feishu provides an official Markdown -> Blocks conversion endpoint:
CODEBLOCK1
CODEBLOCK2
Pros: No manual Block JSON construction. Handles most standard Markdown.
Limitation: Does not support Feishu-specific blocks (Callout, etc.) — use manual Block creation for those.
| block_type | Name | JSON Key | Notes |
|---|---|---|---|
| 1 | Page | INLINECODE0 | Document root |
| 2 |
text | Paragraph |
| 3-11 | Heading1-9 | heading1-heading9 | Headings |
| 12 | Bullet | bullet | Unordered list (each item = separate block) |
| 13 | Ordered | ordered | Ordered list |
| 14 | Code | code | Code block (with style.language enum) |
| 15 | Quote | quote | Blockquote |
| 17 | Todo | todo | Checkbox item (with style.done) |
| 19 | Callout | callout | Highlight box (Feishu-specific, container block) |
| 22 | Divider | divider | Horizontal rule |
| 27 | Image | image | Two-step: create placeholder, then upload |
| 31 | Table | table | Table |
| 34 | QuoteContainer | quote_container | Quote container |
CODEBLOCK3
block_id: Parent block ID (usually document_id itself for root)CODEBLOCK4
CODEBLOCK5
CODEBLOCK6
Each list item is a separate Block.
CODEBLOCK7
Common language enums: PlainText=1, JavaScript=23, Python=40, TypeScript=49, Go=20, Shell=46, SQL=47, Java=22, Rust=44, C=12, CSS=17, HTML=21, Docker=19.
Callout is a container block — create it first, then add child blocks inside.
CODEBLOCK8
Color enums: Red=1, Orange=2, Yellow=3, Green=4, Blue=5, Purple=6, Grey=7.
CODEBLOCK9
CODEBLOCK10
Apply styles via text_element_style in text_run:
| Property | Type | Effect |
|---|---|---|
| INLINECODE21 | bool | Bold |
| INLINECODE22 |
strikethrough | bool | Strikethrough |underline | bool | Underline |inline_code | bool | Inline code |text_color | int | Text color (same enum as callout colors) |background_color | int | Background color |link.url | string | Hyperlink |
Multiple text_run elements in one block = mixed styles in one paragraph.
| Markdown | block_type | JSON Key |
|---|---|---|
| INLINECODE30 | 3 | INLINECODE31 |
| INLINECODE32 |
heading2 |
| ### H3 | 5 | heading3 |
| Paragraph | 2 | text |
| - item | 12 | bullet |
| 1. item | 13 | ordered |
| Code fence | 14 | code |
| > quote | 15 | quote |
| - [ ] todo | 17 | todo |
| --- | 22 | divider |
|  | 27 | image (two-step) |
| **bold** | -- | text_element_style.bold: true |
| *italic* | -- | text_element_style.italic: true |
| ` code | -- | textelementstyle.inlinecode: true |
| ~~strike~~ | -- | textelementstyle.strikethrough: true |
| text | -- | textelementstyle.link.url |
| (no MD equivalent) | 19 | callout (Feishu-specific) |
## Concurrency & Ordering (Critical)
**Problem**: Concurrent Block creation API calls produce random ordering.
### Solution A: Single Batch Request (Recommended)
Put all blocks in one children array, single API call:
CODEBLOCK11
### Solution B: Serial Writes with Index
For long content requiring multiple requests, execute **serially** with explicit index:
CODEBLOCK12
### Solution C: Collect-Then-Write (Recommended)
CODEBLOCK13
**Never** let the LLM write one paragraph at a time with concurrent API calls.
## Complete Write Flow
1. **Create document**: POST /open-apis/docx/v1/documents with { "foldertoken": " -> returns document
2. **Build Block array**: Convert full content to Block JSON
3. **Batch write**: POST .../documents/{docid}/blocks/{docid}/children?documentrevisionid=-1 with all blocks
4. **Container blocks** (optional): For Callout etc., get blockid from step 3 response, then add children
## Custom Callout Syntax
Since Markdown has no Callout equivalent, use this custom markup:
CODEBLOCK14
| Param | Values | Default | Purpose |
|-------|--------|---------|---------|
| color | red, orange, yellow, green, blue, purple, grey | yellow | Background & border |
| emoji | Any Feishu emoji_id (bulb, star, warning, fire) | bulb | Left icon |
| border | Same as color values | Same as color | Border color (override) |
Common templates:
CODEBLOCK15
## Rate Limits & Constraints
- Max blocks per batch: ~50 recommended
- Long articles: Split by H2/H3 sections, 200-500ms between batches
- Always use documentrevisionid=-1 (latest version)
- Token validity: ~2 hours, cache and refresh before expiry
## Authentication
CODEBLOCK16
## Schema Pitfalls (Battle-tested)
- **No Markdown tables in write ops** — use bullet lists instead (prevents schema errors)
- **No nested code blocks inside lists** — Feishu schema validation is strict on nesting depth
- **Callout is a container** — always requires a two-step create (container first, then children)
- **Each list item = separate Block** — don't try to put multiple items in one block
## References
- Create Blocks API: https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block-children/create
- Block Data Structure: https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/data-structure/block
- Convert API: https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document/convert
- Extended API reference: See FEISHUAPI_HANDBOOK.md` in workspace root该技能支持在以下平台通过对话安装：
帮我安装 SkillHub 和 feishu-doc-write-1776420033 技能
设置 SkillHub 为我的优先技能安装源，然后帮我安装 feishu-doc-write-1776420033 技能
skillhub install feishu-doc-write-1776420033
文件大小: 4.29 KB | 发布时间: 2026-4-17 18:51
