Feishu Bitable SKILL

🚨 Pre-execution Notes

✅ Create Data Table: Supports two modes — ① When requirements are clear, define all fields at once via
```
table.fields
```
during
```
create
```
(reduces API calls); ② For exploratory scenarios, use the default table + modify fields gradually (more stable and adjustable)
⚠️ Empty Rows in Default Table: The default table created by
```
app.create
```
contains empty records (empty rows)! It is recommended to call
```
feishu_bitable_app_table_record.list
```
+
```
batch_delete
```
to remove empty rows before inserting data to avoid data contamination
✅ Before Writing Records: First call
```
feishu_bitable_app_table_field.list
```
to get field type/ui_type
✅ User Field: Defaults to open_id (ou_...), value must be
```
[{id:"ou_xxx"}]
```
(array of objects)
✅ Date Field: Millisecond timestamp (e.g.,
```
1674206443000
```
), not seconds
✅ Single Select Field: String (e.g.,
```
"Option 1"
```
), not an array
✅ Multi Select Field: Array of strings (e.g.,
```
["Option 1", "Option 2"]
```
)
✅ Attachment Field: Must first upload to the current Bitable, use the returned file_token
✅ Batch Limit: ≤500 records per call, split into batches if exceeding (batch operations are atomic)
✅ Concurrency Limit: Concurrent writes are not supported for the same data table, use serial calls + 0.5-1 second delay

📋 Quick Index: Intent → Tool → Required Parameters

User Intent	Tool	action	Required Parameters	Common Optional
Check table fields	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 a 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 a 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 Bitable	feishu_bitable_app	create	name	folder_token
Create data table	feishu_bitable_app_table	create	app_token, name	fields
Create field	feishu_bitable_app_table_field	create	app_token, table_id, field_name, type	property
Create view	feishu_bitable_app_table_view	create	app_token, table_id, view_name, view_type	-

🎯 Core Constraints (Undisclosed Schema Knowledge)

📚 Detailed Reference Documents

When encountering field configuration, record value format issues or needing complete examples, refer to the following documents:

Field Property Configuration Details -
```
property
```
parameter structure required for creating/updating each field type (options for single select, min/max for progress, associated table_id, etc.)
Record Value Data Structure Details -
```
fields
```
value format corresponding to each field type in records (only pass id for user fields, date is millisecond timestamp, attachments need pre-upload, etc.)
Complete Usage Scenario Examples - 8 complete scenario examples (comparison of table creation modes, batch import, filtered query, attachment processing, associated fields, etc.)

When to Refer:

Received error code
```
125408X
```
when creating/updating fields (incorrect property structure) → Check field-properties.md
Received error code
```
125406X
```
when writing records (field value conversion failed) → Check record-values.md
Need complete operation flows and parameter examples → Check examples.md

1. Field Type and Value Format Must Strictly Match

Bitable's Biggest Pitfall: Different field types have completely different requirements for value data structures.

Most Error-Prone Field Types (Full list in record-values.md)

type	ui_type	Field Type	Correct Format	❌ Common Mistakes
11	User	User	`[{id: "ou_xxx"}]`	Pass string `"ou_xxx"` or `[{name: "Zhang San"}]`
5	DateTime	Date	`1674206443000` (milliseconds)	Pass second-level timestamp or string
3	SingleSelect	Single Select	`"Option Name"`	Pass array `["Option Name"]`
4	MultiSelect	Multi Select	`["Option 1", "Option 2"]`	Pass string `"Option 1"`
15	Url	Hyperlink	`{link: "...", text: "..."}`	Pass only string URL
17	Attachment	Attachment	`[{file_token: "..."}]`	Pass external URL or local path

Mandatory Process:

First call

feishu_bitable_app_table_field.list

to get field

type

and

ui_type

Construct the correct format based on the above table or record-values.md
Error code
```
125406X
```
or
```
1254015
```
→ Check field value format

Special Note for User Field:

Defaults to open_id (ou_...), consistent with calendar/task
Format:
```
[{id: "ou_xxx"}]
```
(array of objects)
Only pass the id field, do not pass name/email, etc.

📌 Core Usage Scenarios

Complete Examples: Check examples.md for more scenarios (comparison of table creation modes, empty row processing, attachment upload, associated fields, etc.)

Scenario 1: Query Field Types (Mandatory First Step)

json

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

Return: Includes

field_id

field_name

type

ui_type

property

for each field

Scenario 2: Batch Import Customer Data

json

{
  "action": "batch_create",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "records": [
    {
      "fields": {
        "Customer Name": "Bytedance",
        "Responsible Person": [{"id": "ou_xxx"}],
        "Signing Date": 1674206443000,
        "Status": "In Progress"
      }
    },
    {
      "fields": {
        "Customer Name": "Feishu",
        "Responsible Person": [{"id": "ou_yyy"}],
        "Signing Date": 1675416243000,
        "Status": "Completed"
      }
    }
  ]
}

Field Value Format:

User:
```
[{id: "ou_xxx"}]
```
(array of objects)
Date: Millisecond timestamp
Single Select: String
Multi Select: Array of strings

Limit: Maximum 500 records

Scenario 3: Filtered Query (Advanced Filter)

json

{
  "action": "list",
  "app_token": "S404b...",
  "table_id": "tbl...",
  "filter": {
    "conjunction": "and",
    "conditions": [
      {
        "field_name": "Status",
        "operator": "is",
        "value": ["In Progress"]
      },
      {
        "field_name": "Deadline",
        "operator": "isLess",
        "value": ["ExactDate", "1740441600000"]
      }
    ]
  },
  "sort": [
    {
      "field_name": "Deadline",
      "desc": false
    }
  ]
}

filter Description:

Supports 10 operators (is/isNot/contains/isEmpty, etc., see Appendix C)
⚠️ isEmpty/isNotEmpty must pass
value: []
(logically no value is needed, but API requires empty array)
Date filtering can use
```
["Today"]
```
,
```
["ExactDate", "timestamp"]
```
, etc.
```
sort
```
can specify multiple sorting fields

🔍 Common Errors and Troubleshooting

Error Code	Symptom	Root Cause	Solution
1254064	DatetimeFieldConvFail	Incorrect date field format	Must use millisecond timestamp (e.g., `1772121600000` ), do not use string ("2026-02-27", RFC3339) or second-level timestamp
1254068	URLFieldConvFail	Incorrect hyperlink field format	Must use object `{text: "Display Text", link: "URL"}` , do not pass string URL directly
1254066	UserFieldConvFail	Incorrect user field format or mismatched ID type	Must pass `[{id: "ou_xxx"}]` , confirm `user_id_type`
1254015	Field types do not match	Field value format does not match type	First list fields, then construct correct format by type
1254104	RecordAddOnceExceedLimit	Batch creation exceeds 500 records	Call in batches, ≤500 records per batch
1254291	Write conflict	Concurrent write conflict	Use serial calls + 0.5-1 second delay
1254303	AttachPermNotAllow	Attachment not uploaded to current table	First call the material upload interface
1254045	FieldNameNotFound	Field name does not exist	Check field name (including spaces, case sensitivity)

📚 Appendix: Background Knowledge

A. Resource Hierarchy

App (Bitable App)
 ├── Table (Data Table) ×100
 │    ├── Record (Row) ×20,000
 │    ├── Field (Column) ×300
 │    └── View ×200
 └── Dashboard

B. Filter Operator List

operator	Meaning	Supported Fields	Value Requirement
`is`	Equals	All	Single value
`isNot`	Not Equals	All except date	Single value
`contains`	Contains	All except date	Multiple values allowed
`doesNotContain`	Does Not Contain	All except date	Multiple values allowed
`isEmpty`	Is Empty	All	Must be `[]`
`isNotEmpty`	Is Not Empty	All	Must be `[]`
`isGreater`	Greater Than	Number, Date	Single value
`isGreaterEqual`	Greater Than or Equal	Number (not supported for date)	Single value
`isLess`	Less Than	Number, Date	Single value
`isLessEqual`	Less Than or Equal	Number (not supported for date)	Single value

Special Values for Date Field:

["Today"]

["Tomorrow"]

["ExactDate", "timestamp"]

, etc. (full list in examples.md)

C. Usage Limits

Limit Item	Upper Limit
Data Tables + Dashboards	100 (per App)
Number of Records	20,000 (per Data Table)
Number of Fields	300 (per Data Table)
Number of Views	200 (per Data Table)
Batch Create/Update/Delete	500 (per API call)
Cell Text	100,000 characters
Single Select/Multi Select Options	20,000 (per field)
Cell Attachments	100
Cell Users	1,000

D. Other Constraints

Data tables synchronized from other data sources do not support adding/deleting/modifying records
Formula fields, view reference fields are read-only
Delete operations cannot be recovered
View filter conditions use
```
field_id
```
, need to call field.list first to get it

feishu-bitable

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Bitable SKILL

🚨 Pre-execution Notes

📋 Quick Index: Intent → Tool → Required Parameters

🎯 Core Constraints (Undisclosed Schema Knowledge)

📚 Detailed Reference Documents

1. Field Type and Value Format Must Strictly Match

Most Error-Prone Field Types (Full list in record-values.md)

📌 Core Usage Scenarios

Scenario 1: Query Field Types (Mandatory First Step)

Scenario 2: Batch Import Customer Data

Scenario 3: Filtered Query (Advanced Filter)

🔍 Common Errors and Troubleshooting

📚 Appendix: Background Knowledge

A. Resource Hierarchy

B. Filter Operator List

C. Usage Limits

D. Other Constraints