feishu

Feishu Open Platform API を curl + jq で操作します。ユーザーの OAuth user_access_token は $FEISHU_TOKEN に格納されています。すべての呼び出しで Authorization: Bearer $FEISHU_TOKEN として送信します。すべてのエンドポイントは https://open.feishu.cn/open-apis の下にあります。

呼び出しはユーザーのコンテキスト（ユーザーのドキュメント、カレンダー、メッセージ）で実行されます。ユーザーがアクセスできるデータと、接続時に許可したスコープ（docs / sheets / base / drive / calendar / IM / wiki / task / contacts）のみが対象です。

レスポンス形式とエラー処理

Feishu のレスポンスはすべて {"code": 0, "msg": "success", "data": {…}} です。 code == 0 は成功を意味します。code が 0 以外の場合はエラーです。msg をユーザーに表示してください。必ず確認してください。

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

よくあるエラーコード：

code	意味	対応
99991663 / 99991668	アクセストークンが無効／期限切れ	接続設定で Feishu に再接続するようユーザーに伝えてください
99991661	権限がありません（スコープが許可されていません）	接続時のスコープが不足しています。再接続して許可してください
1254xxx	リソースが見つからない／アクセスできない	ユーザーがそのドキュメント／シート／アプリを表示できません。トークン／IDを再確認してください

使用例

認証の確認（必ず最初に実行）

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'

ドキュメント（docx）

Feishu のドキュメント URL は https://…feishu.cn/docx/<document_id> の形式です。 document_id はパスの最後のセグメントです。

ドキュメントのプレーンテキストを読み取ります。

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'

ドキュメントのブロック（構造化コンテンツ）を一覧表示します。

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'

新しい空のドキュメントを作成します（フォルダー内にも作成できます）。

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'

ドキュメントにテキストブロックを追加します（ドキュメント本文の末尾に挿入します。 DOCUMENT_ID はルートブロック ID でもあります）。

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'

スプレッドシート（sheets v2）

シートの URL は https://…feishu.cn/sheets/<spreadsheet_token> の形式です。 範囲は <sheetId>!<A1:range> です（例：abc123!A1:D10）。シート ID が不明な場合は、先にメタ情報エンドポイントで一覧表示してください。

範囲を読み取ります。

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'

最後の空でない行の後に行を追加します。

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）

Base の URL は https://…feishu.cn/base/<app_token> の形式です。table_id は …/bitable/v1/apps/APP_TOKEN/tables から取得します。

レコードを一覧表示します。

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'

レコードを作成します。

curl -sS -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/APP_TOKEN/tables/TABLE_ID/records" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{fields: {"标题": "新任务", "状态": "待办"}}')" \
  | jq 'if .code == 0 then {record_id: .data.record.record_id} else . end'

Drive ファイル

フォルダー内のファイルを一覧表示します（ルートの場合は folder_token を省略します）。

curl -sS "https://open.feishu.cn/open-apis/drive/v1/files?folder_token=FOLDER_TOKEN&page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.files[] | {name, type, token, url}] else . end'

カレンダー（v4）

ユーザーのカレンダーを一覧表示します（メインのカレンダーは type: "primary" です）。

curl -sS "https://open.feishu.cn/open-apis/calendar/v4/calendars?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.calendar_list[] | {calendar_id, summary, type}] else . end'

指定した期間のイベントを一覧表示します（エポック秒の文字列を使用）。

curl -sS "https://open.feishu.cn/open-apis/calendar/v4/calendars/CALENDAR_ID/events?start_time=1751299200&end_time=1751385600&page_size=100" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {summary, start: .start_time, end: .end_time, event_id}] else . end'

イベントを作成します（時刻にはエポック秒の文字列を使用）。

curl -sS -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/CALENDAR_ID/events" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{summary: "项目评审", start_time: {timestamp: "1751302800"}, end_time: {timestamp: "1751306400"}}')" \
  | jq 'if .code == 0 then {event_id: .data.event.event_id} else . end'

タスク（v2）

ユーザーのタスクを一覧表示します。

curl -sS "https://open.feishu.cn/open-apis/task/v2/tasks?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {summary, completed_at, task_guid: .guid}] else . end'

タスクを作成します。

curl -sS -X POST "https://open.feishu.cn/open-apis/task/v2/tasks" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{summary: "准备周会材料"}')" \
  | jq 'if .code == 0 then {task_guid: .data.task.guid} else . end'

Wiki

Wiki のスペースを一覧表示し、次にスペース内のノードを一覧表示します。

curl -sS "https://open.feishu.cn/open-apis/wiki/v2/spaces?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {space_id, name}] else . end'

curl -sS "https://open.feishu.cn/open-apis/wiki/v2/spaces/SPACE_ID/nodes?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {title, node_token, obj_type}] else . end'

IM メッセージの送信

open_id を使ってユーザーに送信します（グループチャットの場合は receive_id_type=chat_id を使用します）。content は JSON の文字列である必要があるため、二重にエンコードします。

curl -sS -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg rid "ou_xxx" --arg text "你好，这是助手发送的消息。" '
    {receive_id: $rid, msg_type: "text", content: ({text: $text} | tostring)}')" \
  | jq 'if .code == 0 then {message_id: .data.message_id} else . end'

注意事項

• メッセージの送信、カレンダーへの招待の作成、共有ドキュメントへの投稿など、破壊的な操作や外部に影響する操作を実行する前に、ユーザーに確認してください。
• ページネーション：一覧エンドポイントは data.page_token / data.has_more を返します。次のページを取得するには page_token=… を渡してください。
• ユーザーが Feishu のリンクを貼り付けた場合は、IDを尋ねるのではなく、URL のパスからトークン／IDを抽出してください。