---

name: feishu-api-lookup description: | Look up Feishu Open API documentation. Activate when: needing to find a specific Feishu API endpoint, understanding API parameters/response, writing scripts that call Feishu APIs, or troubleshooting Feishu API errors. Uses web_search + web_fetch to find and extract API docs in real-time.

Feishu API Lookup

Query Feishu Open Platform API documentation on demand. Since the Feishu docs site is a SPA that can't be statically scraped, this skill uses web search + page fetch to find API docs in real-time.

When to Use

• Need to find a Feishu API endpoint (e.g., "how to forward a thread")
• Need to understand API parameters, request/response format
• Writing a Python/Node script that calls Feishu APIs
• Troubleshooting Feishu API error codes
• The built-in OpenClaw feishu plugin doesn't support the needed operation

How to Look Up

Step 1: Search for the API

Use web_search with targeted queries:

web_search("飞书 open API {你要找的功能} site:open.feishu.cn")

Search tips:

• Use Chinese keywords for better results: "发送消息", "转发话题", "合并转发", "创建文档", "多维表格"
• Add site:open.feishu.cn to limit to official docs
• Add POST /im/v1/ or similar path patterns if you know the API domain
• Alternative: search site:feishu.apifox.cn for the Apifox mirror (sometimes more accessible)

Common API domains:

Domain	Path prefix	Description
消息 (IM)	/im/v1/	Messages, threads, reactions, pins
通讯录	/contact/v3/	Users, departments, groups
云文档	/drive/v1/, /docx/v1/	Docs, sheets, files
多维表格	/bitable/v1/	Bitable (multidimensional tables)
知识库	/wiki/v2/	Wiki spaces, nodes
日历	/calendar/v4/	Calendars, events
审批	/approval/v4/	Approvals
任务	/task/v2/	Tasks
群组	/im/v1/chats/	Chat groups
权限	/drive/v1/permissions/	File permissions
应用	/application/v6/	App management

Step 2: Fetch the API doc page

Use web_fetch to get the doc content:

web_fetch("https://open.feishu.cn/document/server-docs/im-v1/message/create", maxChars=15000)

⚠️ The official docs site is SPA-rendered — web_fetch may return empty content.

Fallbacks when web_fetch fails:

1. Try the Apifox mirror: https://feishu.apifox.cn (search for the API there)
2. Search for the Chinese doc URL pattern: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/...
3. Use web_search with more specific queries to find the exact parameters

Step 3: Extract key information

From the doc, extract:

• HTTP Method + URL: e.g., POST /open-apis/im/v1/messages/{message_id}/forward
• Headers: Usually Authorization: Bearer {tenant_access_token} + Content-Type: application/json
• Path params: Variables in the URL
• Query params: Required/optional query parameters
• Request body: JSON structure with field types and descriptions
• Response body: Expected response format
• Error codes: Common errors and fixes
• Required permissions: Which scopes are needed

Authentication

Almost all Feishu APIs need a tenant_access_token. Get it from:

import json, urllib.request

with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
app_id = cfg['channels']['feishu']['appId']
app_secret = cfg['channels']['feishu']['appSecret']

req = urllib.request.Request(
    'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
    data=json.dumps({"app_id": app_id, "app_secret": app_secret}).encode(),
    headers={"Content-Type": "application/json"}
)
token = json.loads(urllib.request.urlopen(req).read())['tenant_access_token']

Common Patterns

Send a request to Feishu API

req = urllib.request.Request(
    f'https://open.feishu.cn/open-apis/{api_path}',
    data=json.dumps(body).encode(),
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {token}"
    }
)
try:
    resp = json.loads(urllib.request.urlopen(req).read())
except urllib.error.HTTPError as e:
    resp = json.loads(e.read().decode())

Pagination pattern

Many list APIs use cursor-based pagination:

page_token = None
all_items = []
while True:
    url = f'https://open.feishu.cn/open-apis/{path}?page_size=50'
    if page_token:
        url += f'&page_token={page_token}'
    resp = fetch(url)
    all_items.extend(resp['data']['items'])
    if not resp['data'].get('has_more'):
        break
    page_token = resp['data']['page_token']

Frequently Used APIs (Quick Reference)

Messages (IM)

Action	Method	Path
Send message	POST	/im/v1/messages?receive_id_type={type}
Reply to message	POST	/im/v1/messages/{message_id}/reply
Forward message	POST	/im/v1/messages/{message_id}/forward?receive_id_type={type}
Merge forward	POST	/im/v1/messages/merge_forward?receive_id_type={type}
Forward thread	POST	/im/v1/threads/{thread_id}/forward?receive_id_type={type}
Get message	GET	/im/v1/messages/{message_id}
List messages	GET	/im/v1/messages?container_id_type=chat&container_id={id}
Delete message	DELETE	/im/v1/messages/{message_id}
Update message	PATCH	/im/v1/messages/{message_id}
Add reaction	POST	/im/v1/messages/{message_id}/reactions
Get message file	GET	/im/v1/messages/{message_id}/resources/{file_key}?type={type}

Groups (Chat)

Action	Method	Path
Create group	POST	/im/v1/chats
Get group info	GET	/im/v1/chats/{chat_id}
List members	GET	/im/v1/chats/{chat_id}/members
Add members	POST	/im/v1/chats/{chat_id}/members

Docs

Action	Method	Path
Create document	POST	/docx/v1/documents
Get document content	GET	/docx/v1/documents/{document_id}/raw_content
List blocks	GET	/docx/v1/documents/{document_id}/blocks
Create block	POST	/docx/v1/documents/{document_id}/blocks/{block_id}/children
Update block	PATCH	/docx/v1/documents/{document_id}/blocks/{block_id}
Delete block	DELETE	/docx/v1/documents/{document_id}/blocks/{block_id}/children/batch_delete

Drive

Action	Method	Path
Upload file	POST	/drive/v1/medias/upload_all
List folder	GET	/drive/v1/files?folder_token={token}
Get file info	GET	/drive/v1/metas/batch_query
Move file	POST	/drive/v1/files/{file_token}/move

Bitable

Action	Method	Path
List records	GET	/bitable/v1/apps/{app_token}/tables/{table_id}/records
Create record	POST	/bitable/v1/apps/{app_token}/tables/{table_id}/records
Update record	PUT	/bitable/v1/apps/{app_token}/tables/{table_id}/records/{record_id}
List fields	GET	/bitable/v1/apps/{app_token}/tables/{table_id}/fields
Search records	POST	/bitable/v1/apps/{app_token}/tables/{table_id}/records/search

Wiki

Action	Method	Path
List spaces	GET	/wiki/v2/spaces
Get node	GET	/wiki/v2/spaces/get_node?token={token}
List nodes	GET	/wiki/v2/spaces/{space_id}/nodes
Create node	POST	/wiki/v2/spaces/{space_id}/nodes

Permissions

Action	Method	Path
List permissions	GET	/drive/v1/permissions/{token}/members?type={type}
Add permission	POST	/drive/v1/permissions/{token}/members?type={type}
Remove permission	DELETE	/drive/v1/permissions/{token}/members/{member_id}?type={type}

Error Handling

Common error codes:

• 99991663 — Invalid tenant_access_token (expired or wrong)
• 99991668 — Invalid user_access_token
• 230001 — Invalid request parameter
• 230002 — Bot not in group
• 230013 — User not in bot's availability scope
• 230020 — Rate limit exceeded
• 230027 — Insufficient permissions

Tips

1. Always use the /open-apis/ prefix in the full URL: https://open.feishu.cn/open-apis/im/v1/messages
2. Token expires in 2 hours — cache it but refresh before expiry
3. receive_id_type matters — open_id for users, chat_id for groups, union_id for cross-app
4. File uploads use multipart/form-data, not JSON
5. Feishu vs Lark — same API, different domain (open.feishu.cn vs open.larksuite.com)