All-in-one Guide for Feishu Bitable

You are an automation expert for Feishu Bitable, responsible for implementing data operations, structure management, view configuration, and permission control via Bitable API.

1. Basic API Information

Item	Value
Base URL	`https://open.feishu.cn/open-apis/bitable/v1`
Authentication Method	`Authorization: Bearer {tenant_access_token}`
Content-Type	`application/json`

Key Parameter Acquisition

Parameter	Obtaining Method
`app_token`	The string after `/base/` in the Bitable URL
`table_id`	Obtain by calling the list data tables API, or extract from URL parameters

2. Record Operations (CRUD)

1. Add a Single Record

POST /apps/{app_token}/tables/{table_id}/records

json

{
  "fields": {
    "名称": "测试记录",
    "金额": 100,
    "日期": 1770508800000,
    "状态": "进行中"
  }
}

Practical Tips: Do not pass strings for numeric types; dates must be 13-digit millisecond timestamps.

2. Batch Add Records

POST /apps/{app_token}/tables/{table_id}/records/batch_create

json

{
  "records": [
    { "fields": { "名称": "记录1" } },
    { "fields": { "名称": "记录2" } }
  ]
}

Practical Tips: Maximum 500 records per request. Idempotent writes (Upsert) can be achieved by specifying a unique index field.

3. Update Record

PUT /apps/{app_token}/tables/{table_id}/records/{record_id}

json

{
  "fields": { "状态": "已完成" }
}

4. Batch Update Records

POST /apps/{app_token}/tables/{table_id}/records/batch_update

Practical Tips: It is recommended to control the upper limit of a single request within 500 records.

5. Batch Delete Records

POST /apps/{app_token}/tables/{table_id}/records/batch_delete

json

{ "records": ["rec_1", "rec_2"] }

Practical Tips: Maximum 500 records per request. Used for automated cleanup of test data or outdated logs.

6. Query Records

POST /apps/{app_token}/tables/{table_id}/records/search

json

{
  "field_names": ["名称", "金额"],
  "filter": {
    "conjunction": "and",
    "conditions": [
      { "field_name": "状态", "operator": "is", "value": ["进行中"] }
    ]
  },
  "sort": [
    { "field_name": "金额", "desc": true }
  ]
}

Practical Tips: The Filter syntax is relatively complex; it is recommended to debug with reference to the documentation.

3. Writing Formats for Field Types (Critical)

Different field types have different data formats; incorrect formats will cause API errors.

Complete Field Type Comparison Table

type	ui_type	Chinese Name	Writing Format	Example
1	Text	Multi-line Text	String	`"办公用品"`
1	Email	Email	String	`"test@example.com"`
2	Number	Number	Numeric Value	`100`
2	Currency	Currency	Numeric Value	`1280.50`
2	Progress	Progress	Numeric Value (0~1)	`0.25`
2	Rating	Rating	Numeric Value (1~5)	`3`
3	SingleSelect	Single Select	String	`"支出"`
4	MultiSelect	Multi Select	String Array	`["餐饮","交通"]`
5	DateTime	Date & Time	Millisecond Timestamp	`1770508800000`
7	Checkbox	Checkbox	Boolean	`true`
11	User	User	Object Array	`[{"id":"ou_xxx"}]`
13	Phone	Phone	String	`"13800138000"`
15	Url	Hyperlink	Object	`{"text":"名称","link":"https://..."}`
17	Attachment	Attachment	Object Array	`[{"file_token":"xxx"}]`
18	SingleLink	Single-way Association	String Array	`["recuxxx"]`
21	DuplexLink	Two-way Association	String Array	`["recuxxx"]`
22	Location	Location	String	`"116.397,39.903"`

Field Types Not Supported for API Writing

The following fields are automatically maintained by the system; they do not need to and cannot be written via API:

Lookup Reference (type=19), Formula (type=20), Creation Time (type=1001), Last Update Time (type=1002), Creator (type=1003), Modifier (type=1004), Auto Number (type=1005), Button (type=3001)

Date Field Conversion (Most Common Pitfall)

Dates must be converted to 13-digit millisecond timestamps:

python

import datetime
ts = int(datetime.datetime(2026, 2, 9).timestamp() * 1000)
# → 1770508800000

4. Field Management

7. Get Field List

GET /apps/{app_token}/tables/{table_id}/fields

Practical Tips: Returns the

type

and

ui_name

of fields, which is the foundation for implementing a "universal adapter" to dynamically adapt to the structure of Bitable tables in different projects.

8. Add Field

POST /apps/{app_token}/tables/{table_id}/fields

json

{ "field_name": "新字段", "type": 1 }

Practical Tips: It takes a few seconds for the index to take effect after adding a field.

9. Update Field Configuration

PUT /apps/{app_token}/tables/{table_id}/fields/{field_id}

Practical Tips: When modifying single-select/multi-select fields, the complete

property

structure (including all options) must be provided.

10. Insert Formula Field

POST /apps/{app_token}/tables/{table_id}/fields

json

{
  "type": 20,
  "field_name": "利润",
  "property": { "formula_expression": "[营收]-[成本]" }
}

Practical Tips: The formula syntax follows Feishu standards; cross-table references are not supported.

11. Insert Association Field

POST /apps/{app_token}/tables/{table_id}/fields

json

{
  "type": 18,
  "field_name": "关联客户",
  "property": { "table_id": "tblXXX", "multiple": true }
}

Practical Tips: The core of implementing Relational Database (RDBMS) capabilities.

5. Data Table Management

12. Create Bitable

POST /open-apis/bitable/v1/apps

json

{ "name": "数据库名称" }

Practical Tips: Bitable is an independent application, and its path is different from Docx.

13. Get Table-level Metadata

GET /apps/{app_token}/tables/{table_id}

Practical Tips: Includes total number of records, whether there are unsynced external references, etc. Used for inspecting database health.

14. Rename Data Table

PATCH /apps/{app_token}/tables/{table_id}

json

{ "name": "新表名" }

15. Copy Bitable

POST /open-apis/drive/v1/files/{file_token}/copy

Practical Tips: Although it is a Drive interface, it is suitable for overall cloning of Bitable files. Quickly clone from standard templates when starting new projects.

6. View Management

16. Create Kanban View

POST /apps/{app_token}/tables/{table_id}/views

json

{ "view_name": "今日看板", "view_type": "kanban" }

17. Create Gantt View

json

{ "view_name": "项目排期", "view_type": "gantt" }

Practical Tips: Gantt charts require specifying start/end date fields.

18. Create Form View

json

{ "view_type": "form" }

Practical Tips: The generated URL can be distributed via bots, and customer submissions are directly sent to the database.

19. Set View Filter Conditions

PATCH /apps/{app_token}/tables/{table_id}/views/{view_id}

json

{
  "property": {
    "filter_info": {
      "conditions": [
        { "field_name": "状态", "operator": "is", "value": ["进行中"] }
      ]
    }
  }
}

Practical Tips: Very suitable for creating dynamic Dashboards.

20. Manage View Display Columns

POST /apps/{app_token}/tables/{table_id}/views/{view_id}/display_fields

Practical Tips: Improve loading and reading experience of large tables by configuring column visibility.

21. Create Dashboard

POST /apps/{app_token}/dashboards/copy

Practical Tips: Currently mainly supports copying from templates. Automatically build data dashboards after project initiation.

7. Roles and Permissions

22. Get Role List

GET /apps/{app_token}/roles

Practical Tips: Automatically audit who has export permissions. The cornerstone of enterprise-level security control.

23. Create Custom Role

POST /apps/{app_token}/roles

Practical Tips: Need to cooperate with

role_configuration

to finely set field permissions. Dynamically create permission groups for suppliers that "can only view their own data".

24. Manage Role Members

POST /apps/{app_token}/roles/{role_id}/members

Practical Tips: Supports batch addition, greatly reducing operation and maintenance costs. Automatically add new employees to specific permission groups.

25. Manage Collaboration Permissions

Permission:

docs:permission.setting:write_only

Practical Tips: Call the general permission interface of cloud documents. Automatically switch edit permissions to read-only after project completion.

8. Statistics and Advanced Features

26. Get Statistics Information

GET /apps/{app_token}/tables/{table_id}/statistics

Practical Tips: Lighter weight than directly pulling records. Suitable for regular reporting such as "number of new orders yesterday".

27. Trigger Automated Workflow

Practical Tips: Records written via API can also trigger the internal "Automation Assistant" of Bitable (no additional permissions required).

9. Attachment Upload Process

To upload files to Bitable attachment fields, two steps are required:

Step 1: Upload File to Get file_token

POST https://open.feishu.cn/open-apis/drive/v1/medias/upload_all
Content-Type: multipart/form-data

- file: File
- file_name: "invoice.jpg"
- parent_type: "bitable_file"
- parent_node: "{app_token}"
- size: File size (bytes)

Step 2: Write file_token to Attachment Field

json

{
  "fields": {
    "附件字段名": [{"file_token": "返回的file_token"}]
  }
}

10. Error Handling

Error Code	Meaning	Solution
0	Success	—
1254043	No Permission	Add the app to Bitable
1254044	Invalid app_token	Check the token in the Bitable URL
1254045	Invalid table_id	Re-obtain by calling the list data tables API
1254607	Incorrect Field Value Format	Check if the field type matches the value format
99991663	Token Expired	Re-obtain tenant_access_token
99991400	Rate Limit	Retry after 1 second

feishu-bitable

NPX Install

Tags

SKILL.md Content (Chinese)

All-in-one Guide for Feishu Bitable

1. Basic API Information

Key Parameter Acquisition

2. Record Operations (CRUD)

1. Add a Single Record

2. Batch Add Records

3. Update Record

4. Batch Update Records

5. Batch Delete Records

6. Query Records

3. Writing Formats for Field Types (Critical)

Complete Field Type Comparison Table

Field Types Not Supported for API Writing

Date Field Conversion (Most Common Pitfall)

4. Field Management

7. Get Field List

8. Add Field

9. Update Field Configuration

10. Insert Formula Field

11. Insert Association Field

5. Data Table Management

12. Create Bitable

13. Get Table-level Metadata

14. Rename Data Table

15. Copy Bitable

6. View Management

16. Create Kanban View

17. Create Gantt View

18. Create Form View

19. Set View Filter Conditions

20. Manage View Display Columns

21. Create Dashboard

7. Roles and Permissions

22. Get Role List

23. Create Custom Role

24. Manage Role Members

25. Manage Collaboration Permissions

8. Statistics and Advanced Features

26. Get Statistics Information

27. Trigger Automated Workflow

9. Attachment Upload Process

10. Error Handling