Skill: deadblue22/feishu-api-lookup (version 1.0.0)

--- 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: ```python 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"} ) [REDACTED_SECRET]).read())['tenant_access_token'] ``` ## Common Patterns ### Send a request to Feishu API ```python 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: ```python 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?[REDACTED_SECRET]` | | 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`)


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)