feishu

Files (1)

• SKILL.md

SKILL.md (first lines)

We drive the [Feishu Open Platform API](https://open.feishu.cn/document)
with `curl + jq`. The user's OAuth `user_access_token` is in
`$FEISHU_TOKEN`; every call sends it as `Authorization: Bearer
$FEISHU_TOKEN`. All endpoints live under `https://open.feishu.cn/open-apis`.

Calls run **in the user's context** (their docs, calendar, messages) — only
data the user can access and only the scopes they granted at connect time
(docs / sheets / base / drive / calendar / IM / wiki / task / contacts).

## Response shape & error handling

Every Feishu response is `{"code": 0, "msg": "success", "data": {…}}`.
**`code == 0` means success**; any non-zero `code` is an error — surface
`msg` to the user. Always check it:

```sh
resp=$(curl -sS … )
echo "$resp" | jq 'if .code == 0 then .data else error("Feishu \(.code): \(.msg)") end'
```

Common error codes:

| code | meaning | what to do |
|---|---|---|
| `99991663` / `99991668` | access token invalid / expired | tell the user to reconnect Feishu in 连接 settings |
| `99991661` | no permission (scope not granted) | the connect-time scope is missing — reconnect and grant it |
| `1254xxx` | resource not found / no access | the user can't see that doc / sheet / app — double-check the token/id |

## Recipes

### Verify auth (always run first)

```sh
curl -sS https://open.feishu.cn/open-apis/authen/v1/user_info \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then {name: .data.name, open_id: .data.open_id, email: .data.email} else . end'
```

### Docs (docx)

A Feishu doc URL looks like `https://…feishu.cn/docx/<document_id>`. The
`document_id` is the last path segment.

Read a document's plain text:

```sh
curl -sS "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/raw_content" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq -r 'if .code == 0 then .data.content else "ERR \(.code): \(.msg)" end'
```

List a document's blocks (structured content):

```sh
curl -sS "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/blocks?page_size=500" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {block_id, block_type}] else . end'
```

Create a new empty document (optionally inside a folder):

```sh
curl -sS -X POST "https://open.feishu.cn/open-apis/docx/v1/documents" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg title "会议纪要 2026-07-01" '{title: $title}')" \
  | jq 'if .code == 0 then {document_id: .data.document.document_id} else . end'
```

Append a text block to a document (insert at the end of the document body —
`DOCUMENT_ID` is also the root block id):

```sh
curl -sS -X POST "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/blocks/DOCUMENT_ID/children" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg text "由助手追加的一段内容。" '
    {children: [{block_type: 2, text: {elements: [{text_run: {content: $text}}]}}]}')" \
  | jq 'if .code == 0 then "appended" else . end'
```

### Spreadsheets (sheets v2)

A sheet URL looks like `https://…feishu.cn/sheets/<spreadsheet_token>`.
A range is `<sheetId>!<A1:range>`, e.g. `abc123!A1:D10`. List sheet ids via
the metainfo endpoint first if you don't have one.

Read a range:

```sh
curl -sS "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/SPREADSHEET_TOKEN/values/RANGE" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then .data.valueRange.values else . end'
```

Append rows after the last non-empty row:

```sh
curl -sS -X POST "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/SPREADSHEET_TOKEN/values_append" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{valueRange: {range: "SHEET_ID!A1:B1", values: [["张三", 100], ["李四", 200]]}}')" \
  | jq 'if .code == 0 then .data.updates else . end'
```

### Base / 多维表格 (bitable v1)

A Base URL looks like `https://…feishu.cn/base/<app_token>`. Get `table_id`
from `…/bitable/v1/apps/APP_TOKEN/tables`.

List records:

```sh
curl -sS "https://open.feishu.cn/open-apis/bitable/v1/apps/APP_TOKEN/tables/TABLE_ID/records?page_size=100" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {record_id, fields}] else . end'
```

Create a record:

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills