SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsfeishu-bitable

feishu-bitable

Data & analytics

View repository

Updated 10-15 23:48

About this skill

Feishu Bitable (多维表格) SKILL

🚨 Must-read before execution

  • ✅ Create a data table: Supports two modes — ① When requirements are clear, at create define fields all at once via table.fields (reduces API calls); ② In exploratory scenarios, use the default table + modify fields step by step (more stable, easier to adjust)
  • ⚠️ Empty-row pitfall of the default table：app.create The built-in default table contains empty records (empty rows)! Before inserting data, it is recommended to first call feishu_bitable_app_table_record.list + batch_delete to delete empty rows and avoid data pollution
  • ✅ Before writing records: First call feishu_bitable_app_table_field.list to get the field type/ui_type
  • ✅ Person field: Defaults to open_id (ou_...), the value must be [{id:"ou_xxx"}](array of objects)
  • ✅ Date field: millisecond timestamp (for example 1674206443000), not seconds
  • ✅ Single select field: string (for example "选项1"), not an array
  • ✅ Multi-select field: array of strings (for example ["选项1", "选项2"]）
  • ✅ Attachment field: must first be uploaded to the current Bitable, use the returned file_token
  • ✅ Batch limit: ≤ 500 per request, exceeding requires batching (batch operations are atomic)
  • ✅ Concurrency limit: Concurrent writes are not supported for the same data table; serial calls + 0.5-1 second delay are required

📋 Quick index: intent → tool → required parameters

User intent Tool action Required parameters Common optional
Check which fields the table has feishu_bitable_app_table_field list app_token, table_id -
Query records feishu_bitable_app_table_record list app_token, table_id filter, sort, field_names
Add one row feishu_bitable_app_table_record create app_token, table_id, fields -
Batch import feishu_bitable_app_table_record batch_create app_token, table_id, records (≤500) -
Update one row feishu_bitable_app_table_record update app_token, table_id, record_id, fields -
Batch update feishu_bitable_app_table_record batch_update app_token, table_id, records (≤500) -
Create a Bitable feishu_bitable_app create name folder_token
Create a data table feishu_bitable_app_table create app_token, name fields
Create a field feishu_bitable_app_table_field create app_token, table_id, field_name, type property
Create a view feishu_bitable_app_table_view create app_token, table_id, view_name, view_type -

🎯 Core constraints (knowledge not revealed by the Schema)

📚 Detailed reference documentation

When encountering field configuration or record value format issues, or when complete examples are needed, consult the following documents：

  • Field Property configuration details - The property parameter structure required when creating/updating each field type (options for single select, min/max for progress, table_id for links, etc.)
  • Record value data structure details - The fields value format corresponding to each field type in a record (person fields only pass id, dates are millisecond timestamps, attachments must be uploaded first, etc.)
  • Complete usage scenario examples - 8 complete scenario examples (comparison of table creation modes, batch import, filtered query, attachment handling, linked fields, etc.)

When to consult:

  • When creating/updating fields and receiving 125408X error code (property structure error) → consult field-properties.md
  • Received when writing records 125406X error code (field value conversion failed) → see record-values.md
  • Need the complete operation workflow and parameter examples → see examples.md

1. Field types and value formats must strictly match

The biggest pitfall of Bitable: different field types have completely different data structure requirements for value.

The most error-prone field types (see the full list in record-values.md）

type ui_type Field type Correct format ❌ Common mistakes
11 User User [{id: "ou_xxx"}] Passing a string "ou_xxx" or [{name: "张三"}]
5 DateTime Date 1674206443000(milliseconds) Passing a seconds timestamp or string
3 SingleSelect Single select "选项名" Passing an array ["选项名"]
4 MultiSelect Multi-select ["选项1", "选项2"] Passing a string "选项1"
15 Url Hyperlink {link: "...", text: "..."} Passing only a string URL
17 Attachment Attachment [{file_token: "..."}] Passing an external URL or local path

Mandatory workflow：

  1. First call feishu_bitable_app_table_field.list to get the field's type and ui_type
  2. According to the table above or record-values.md construct the correct format
  3. Error code 125406X or 1254015 → check the field value format

Special attention to the User field：

  • Use open_id (ou_...) by default, consistent with calendar/task
  • Format:[{id: "ou_xxx"}](array of objects)
  • Only the id field can be passed, name/email etc. cannot be passed

📌 Core use cases

Complete examples: consult examples.md to learn more scenarios (table creation mode comparison, empty row handling, attachment upload, linked fields, etc.)

Scenario 1: Check field types (mandatory first step)

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl..."
}

Returns: includes each field's field_id、field_name、type、ui_type、property

Scenario 2: Batch import customer data

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "客户名称": "Bytedance",
        "负责人": [{"id": "ou_xxx"}],
        "签约日期": 1674206443000,
        "状态": "进行中"
      }
    },
    {
      "fields": {
        "客户名称": "飞书",
        "负责人": [{"id": "ou_yyy"}],
        "签约日期": 1675416243000,
        "状态": "已完成"
      }
    }
  ]
}

Field value formats：

  • User:[{id: "ou_xxx"}](array of objects)
  • Date: millisecond timestamp
  • Single select: string
  • Multi-select: array of strings

Limit: at most 500 records

Scenario 3: Filter query (advanced filtering)

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "状态",
        "operator": "is",
        "value": ["进行中"]
      },
      {
        "field_name": "截止日期",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "截止日期",
      "desc": false
    }
  ]
}

filter description：

  • Supports 10 operators (is/isNot/contains/isEmpty etc., see Appendix C)
  • ⚠️ isEmpty/isNotEmpty must pass value: [](although logically no value is needed, the API requires an empty array to be passed)
  • Date filtering can use ["Today"]、["ExactDate", "时间戳"] etc.
  • sort can specify multiple sort fields

🔍 Common errors and troubleshooting

Error code Error symptom Root cause Solution
1254064 DatetimeFieldConvFail Date field format error Must use a millisecond timestamp(e.g. 1772121600000), a string cannot be used ("2026-02-27", RFC3339) or a second-level timestamp
1254068 URLFieldConvFail Hyperlink field format error Must use an object {text: "显示文本", link: "URL"}, a string URL cannot be passed directly
1254066 UserFieldConvFail User field format error or ID type mismatch Must pass [{id: "ou_xxx"}], confirm user_id_type
1254015 Field types do not match Field value format does not match the type List the fields first, then construct the correct format according to the type
1254104 RecordAddOnceExceedLimit Batch creation exceeds 500 records Call in batches, each batch ≤ 500
1254291 Write conflict Concurrent write conflict Call serially + delay 0.5-1 second
1254303 AttachPermNotAllow The attachment has not been uploaded to the current table Call the upload material API first
1254045 FieldNameNotFound The field name does not exist Check the field name (including spaces and case)

📚 Appendix: Background Knowledge

A. Resource Hierarchy

App (多维表格应用)
 ├── Table (数据表) ×100
 │    ├── Record (记录/行) ×20,000
 │    ├── Field (字段/列) ×300
 │    └── View (视图) ×200
 └── Dashboard (仪表盘)

B. Filter Condition operator List

operator Meaning Supported Fields value Requirements
is Equals All Single value
isNot Not equals Except dates Single value
contains Contains Except dates Multiple values allowed
doesNotContain Does not contain Except dates Multiple values allowed
isEmpty Is empty All Must be []
isNotEmpty Is not empty All Must be []
isGreater Greater than Numbers, dates Single value
isGreaterEqual Greater than or equal to Numbers (dates not supported) Single value
isLess Less than Numbers, dates Single value
isLessEqual Less than or equal to Numbers (dates not supported) Single value

Special values for date fields: ["Today"], ["Tomorrow"], ["ExactDate", "时间戳"] , etc. (for the full list, see examples.md）

C. Usage Limits

Limit Item Upper Limit
Data tables + dashboards 100 (single App)
Number of records 20,000 (single data table)
Number of fields 300 (single data table)
Number of views 200 (single data table)
Batch create/update/delete 500 (single API call)
Cell text 100,000 characters
Single/multiple select options 20,000 (single field)
Cell attachments 100
Cell members 1,000

D. Other Constraints

  • Data tables synced from other data sourcesdo not support adding, deleting, or modifyingrecords
  • Formula fields and lookup reference fields areread-only.
  • Delete operationscannot be recovered
  • View filter conditions use field_id, and field.list must be called first to obtain them