Feishu API Lookup

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:

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)

Groups (Chat)

Docs

Drive

Bitable

Wiki

Permissions

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)