Feishu Bitable API Operations

Provides large AI models with complete capabilities to process Feishu Bitable, supporting operations on data tables, records, fields, and media.

Environment for Skill Developers

node --version v24.13.0

⚠️ Important: About Code Obfuscation

All JavaScript files under the

scripts/

directory of this skill have been obfuscated.

AI Code of Conduct

✅ Allowed: Directly call and execute these scripts, use

--parameter-file-path

to pass parameters

❌ Prohibited: Do not read or analyze the content of

.js

files under the

scripts/

directory, reasons:

Obfuscated code has extremely poor readability and no practical value
Avoid wasting tokens and time
All functional descriptions are fully documented in this document and the
```
references/
```
directory

When Encountering Problems

Refer to documents under the
```
references/
```
directory
Check error messages and error codes output by the script
Do not attempt to read obfuscated code

🎯 Trigger Mapping: User Input → AI Action

User Input Trigger Keywords	AI Execution Action	Corresponding Script
"View records"/"Get records"/"List records"	Run `record/get.js` to query record list	`scripts/record/get.js`
"Add record"/"Create record"/"Insert record"	Run `record/create.js` to create a single record	`scripts/record/create.js`
"Modify record"/"Update record"/"Edit record"	Run `record/update.js` to update a single record	`scripts/record/update.js`
"Delete record"/"Remove record"	Run `record/delete.js` to delete a single record	`scripts/record/delete.js`
"Batch add records"/"Add multiple records"	Run `record/batch-create.js` to batch create records	`scripts/record/batch-create.js`
"Batch modify records"/"Update multiple records"	Run `record/batch-update.js` to batch update records	`scripts/record/batch-update.js`
"Batch delete records"/"Clear records"	Run `record/batch-delete.js` to batch delete records	`scripts/record/batch-delete.js`
"View tables"/"Data table list"	Run `table/list.js` to list all data tables	`scripts/table/list.js`
"Create table"/"Add data table"	Run `table/create-single.js` to create a single data table	`scripts/table/create-single.js`
"Modify table name"/"Rename table"	Run `table/update.js` to update data table name	`scripts/table/update.js`
"Delete table"/"Remove data table"	Run `table/delete-one.js` to delete a single data table	`scripts/table/delete-one.js`
"View fields"/"Column information"	Run `field/list.js` to list all fields	`scripts/field/list.js`
"Add field"/"New column"	Run `field/create.js` to create a field	`scripts/field/create.js`
"Modify field"/"Edit column"	Run `field/update.js` to update a field	`scripts/field/update.js`
"Delete field"/"Remove column"	Run `field/delete.js` to delete a field	`scripts/field/delete.js`
"Upload file"/"Upload image"/"Upload attachment"	Run `media/upload.js` to upload media	`scripts/media/upload.js`
"Get download link"/"Get direct link"	Run `media/file-token-to-url.js` to get file URL	`scripts/media/file-token-to-url.js`

Decision Flow

Does the user request involve Feishu Bitable?
    │
    ├─ Yes → Check specific operation type
    │       │
    │       ├─ Access credential required?
    │       │   └─ Run get-tenant-access-token.js
    │       │
    │       ├─ Need to parse information from URL?
    │       │   └─ Run parse-bitable-url.js
    │       │
    │       └─ Execute specific operation
    │           ├─ Data table operations → table/ scripts
    │           ├─ Record operations → record/ scripts
    │           ├─ Field operations → field/ scripts
    │           └─ Media operations → media/ scripts
    │
    └─ No → Do not use this Skill

How to Use This Skill

Function Overview

This Skill provides complete Feishu Bitable API operation capabilities:

Function Module	Supported Operations
Data Table Management	Create, update, delete data tables (supports batch operations)
Record Operations	CRUD for records, supports batch operations (max 1000 entries per request)
Field Management	Create, update, delete fields, list all fields
Media Upload	Upload files, images and other media, get temporary download links

Output Format

After execution, the Skill will output:

Success: Return operation result data (JSON format), including complete API response
Failure: Return error information, including error code and solution suggestions

Prerequisites

Valid
tenant_access_token
: Required for all API operations
app_token
: Identifies the target Bitable
table_id
: Identifies the target data table (required for some operations)

Parameter Passing Method

Note: All scripts of this Skill use the

--parameter-file-path

parameter to pass configurations, and must be called through parameter files.

AI Invocation Specification: This Skill is specially designed for AI, AI automatically handles the creation and cleanup of temporary files, human users only need to describe requirements in natural language.

AI Automatic Temporary File Management Process

When AI calls this Skill, it must follow the following process to automatically manage temporary files:

javascript

import { createTempParamsFile, cleanupTempFile } from "./scripts/utils";
import { execSync } from "child_process";

// 1. Create temporary parameter file (automatically stored in system temporary directory)
const tempFile = createTempParamsFile(
  {
    tenant_access_token: "xxx",
    app_token: "xxx",
    table_id: "xxx"
    // ... other parameters
  },
  "operation-name"
);

try {
  // 2. Execute script
  const result = execSync(`node scripts/xxx.js --parameter-file-path "${tempFile}"`, { encoding: "utf-8" });
  const data = JSON.parse(result);

  // 3. Process result and return to user
  return formatResultForUser(data);
} finally {
  // 4. Ensure temporary files are cleaned up (regardless of success or failure)
  cleanupTempFile(tempFile);
}

Key Principles:

✅ Temporary files must be created in the system temporary directory (
```
os.tmpdir()
```
)
✅ Clean up temporary files immediately after script execution is completed
✅ Use
```
try...finally
```
to ensure cleanup even if an error occurs
❌ Do not create parameter files in the skill directory or user working directory

Standard Usage Process

Step 1: Obtain Access Credentials

bash

node scripts/get-tenant-access-token.js --parameter-file-path params.json

Parameter file example (

params.json

json

{
  "appId": "cli_xxx",
  "appSecret": "xxx"
}

For detailed credential management rules, please refer to Authentication and Credential Management Guide.

Step 2: Parse Bitable URL

Extract

app_token

and

table_id

from URL:

bash

node scripts/parse-bitable-url.js --parameter-file-path params.json

Step 3: Execute Specific Operations

Select the corresponding script according to requirements:

bash

# Query records
node scripts/record/get.js --parameter-file-path "params.json"

# Create record
node scripts/record/create.js --parameter-file-path "params.json"

# Batch create records
node scripts/record/batch-create.js --parameter-file-path "params.json"

Core Concepts

Concept	Description
Bitable	A ByteDance product that combines the flexibility of spreadsheets and the structured features of databases
Table	A single table in Bitable, similar to an Excel worksheet
Record	A row of data in a data table
Field	The header of a column in a data table, used to set the data type of the column
Media	Uploaded files, images, videos, etc.

Operation Interface Quick Reference

Basic Operations

Action	Script Path	Description
Obtain access credentials	get-tenant-access-token.js	Get `tenant_access_token`
Parse Feishu Bitable URL	parse-bitable-url.js	Extract `app_token` , `table_id` , `view_id` from URL

Table Operations

Action	Script Path	Description
Add a new data table	create-single.js	Support specifying name, view and fields
Add multiple data tables	batch-create.js	Only data table names can be specified
Update data table name	update.js	Update the name of the specified data table
List data tables	list.js	Get ID, version number and name of all data tables
Delete a data table	delete-one.js	Delete by `app_token` and `table_id`
Delete multiple data tables	batch-delete.js	Batch delete multiple data tables

For detailed parameters, please refer to the table reference document directory.

Record Operations

Action	Script Path	Description
Add record	create.js	Add a new record to the data table
Update record	update.js	Update a record in the data table
Query records	get.js	Query up to 500 rows at a time, support pagination
Delete record	delete.js	Delete a record from the data table
Add multiple records	batch-create.js	Add up to 1,000 entries at a time
Update multiple records	batch-update.js	Update up to 1,000 entries at a time
Batch get records	batch-get.js	Query by record ID, up to 100 entries
Delete multiple records	batch-delete.js	Batch delete multiple records

For detailed parameters, please refer to the record reference document directory.

Field Operations

Action	Script Path	Description
Add field	create.js	Add a new field to the data table
Update field	update.js	Full update field (properties will be overwritten)
List fields	list.js	Get all fields in the data table
Delete field	delete.js	Delete a field from the data table

For detailed parameters, please refer to the field reference document directory.

Media/File Operations

Action	Script Path	Description
Media upload	upload.js	Upload files, images, videos and other media
Get direct link	file-token-to-url.js	Convert `file_token` to temporary download link (valid for 24 hours)

For detailed parameters, please refer to the media reference document directory.

File and Directory Usage Instructions

Item	Description
Document location	Documents under the `references/` directory, with specific API call commands or script execution methods
Script location	Node.js scripts under the `scripts/` directory can be used directly
Temporary files	System temporary directory ( `%TEMP%` or `/tmp` ), automatically deleted after operation is completed
Parameter files	System temporary directory, referenced using absolute paths
Upload records	System temporary directory ( `feishu-bitable-upload-records.json` )

Best Practices for Temporary File Management

All temporary files (parameter files, upload records) of this skill are stored in the system temporary directory to avoid polluting the user's home directory and skill directory:

Windows Example:

C:\Users\xxx\AppData\Local\Temp\feishu-create-record-1740374400000-a7x9k2.json
C:\Users\xxx\AppData\Local\Temp\feishu-bitable-upload-records.json

Linux/Mac Example:

/tmp/feishu-create-record-1740374400000-a7x9k2.json
/tmp/feishu-bitable-upload-records.json

Utility Function Usage Example

javascript

import { createTempParamsFile, cleanupTempFile, cleanupAllTempFiles } from './utils';

// 1. Create temporary parameter file (automatically stored in system temporary directory)
const params = {
  tenant_access_token: 'xxx',
  app_token: 'xxx',
  table_id: 'xxx',
  fields: { ... }
};
const tempFilePath = createTempParamsFile(params, 'create-record');

// 2. Execute script
const result = await executeScript(tempFilePath);

// 3. Clean up temporary files immediately
cleanupTempFile(tempFilePath);

// 4. Clean up all expired temporary files (older than 24 hours)
cleanupAllTempFiles();

Temporary File Naming Convention:

Format:

feishu-{operation}-{timestamp}-{random}.json

Example:

feishu-batch-create-1740374400000-a7x9k2.json

Cleanup Policy:

Try to delete the parameter file immediately regardless of success or failure
Deletion failure does not affect the main process
System temporary directory is automatically cleaned up regularly
Run
```
cleanupAllTempFiles()
```
to batch clean up expired files (older than 24 hours)

AI Processing Example

User says: "Help me add a record to the Feishu table https://xxx.feishu.cn/wiki/xxx, the task name is 'Complete Report', progress 50%"

AI Execution Steps:

Step	Execution Action	Script/Command
1	Check tenant_access_token	If not available, run `get-tenant-access-token.js`
2	Parse URL to get app_token and table_id	Run `parse-bitable-url.js`
3	Create temporary parameter file	Run `createTempParamsFile()` , stored in system temporary directory
4	Create record	Run `record/create.js`
5	Clean up temporary parameter file	Run `cleanupTempFile()`
6	Return result	Return to user: "Record created successfully! Record ID: recxxx"

User Perception: Users do not need to know the existence of temporary files at all, only need to interact in natural language.

Error Handling

Error Scenario	Error Performance	Handling Method
Missing access credentials	API returns 401/403 error	Run `get-tenant-access-token.js` to obtain credentials
Expired access credentials	API returns error code: 99991663, error message: Invalid access token for authorization	Run `get-tenant-access-token.js` to obtain credentials
URL parsing failed	Unable to extract app_token/table_id	Check if the URL format is correct, or provide parameters manually
Record does not exist	API returns 404 error	Check if record_id is correct, or run `record/get.js` to query first
Field type mismatch	API returns 400 error	Run `field/list.js` to view field type, adjust parameters and try again
Text field format error	`TextFieldConvFail` error	Use string format for text fields, do not use rich text array format
Missing parameters for field update	`field validation failed`	Must provide `type` parameter when updating fields
File token format error	`Cannot read properties`	Use `file_tokens` (array) instead of `file_token` (string)
Batch operation exceeds limit	API returns 422 error	Reduce the number of operations per request (max 1000 records, max 100 for batch query)
Temporary file creation failed	Insufficient disk space or permission issues	Check system temporary directory permissions and disk space
Network timeout	No response to request	Check network connection, try again later

Detailed Explanation of Common Errors

1. Text Field Format Error (TextFieldConvFail)

Error Message:

the value of 'Multiline' must be a string

Cause: When creating/updating records, the text field uses the rich text array format returned by the query

Solution:

❌ Wrong:

"Field Name": [{"text": "Content", "type": "text"}]

✅ Correct:
```
"Field Name": "Content"
```

2. Missing

type

Parameter for Field Update

Error Message:

field validation failed - type is required

Cause: The

type

parameter is not provided when updating the field

Solution: The

type

parameter must be included when updating fields, e.g.

"type": 1

(1=text, 2=number)

3. Wrong Parameter for Getting File Download Link

Error Message:

Cannot read properties of undefined (reading 'map')

Cause: Used

file_token

instead of

file_tokens

Solution:

❌ Wrong:
```
"file_token": "xxx"
```
✅ Correct:
```
"file_tokens": ["xxx"]
```

Reference Documents

Document	Description
Authentication and Credential Management Guide	Detailed credential management instructions, including App ID/App Secret acquisition, tenant_access_token automatic acquisition process
Obtain Access Credential API	Specific API call instructions and script usage methods for obtaining tenant_access_token
Feishu URL Parsing Tool	Usage instructions for the tool to extract app_token, table_id, view_id from Feishu Bitable URL
Common Errors and Solutions	Common API call error codes and troubleshooting methods
Parameter Configuration Examples and Best Practices	Parameter configuration examples for various operation scenarios

feishu-bitable

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Bitable API Operations

Environment for Skill Developers

⚠️ Important: About Code Obfuscation

AI Code of Conduct

When Encountering Problems

🎯 Trigger Mapping: User Input → AI Action

Decision Flow

How to Use This Skill

Function Overview

Output Format

Prerequisites

Parameter Passing Method

AI Automatic Temporary File Management Process

Standard Usage Process

Core Concepts

Operation Interface Quick Reference

Basic Operations

Table Operations

Record Operations

Field Operations

Media/File Operations

File and Directory Usage Instructions

Best Practices for Temporary File Management

Utility Function Usage Example

AI Processing Example

Error Handling

Detailed Explanation of Common Errors

1. Text Field Format Error (TextFieldConvFail)

2. Missing
`type`
Parameter for Field Update

3. Wrong Parameter for Getting File Download Link

Reference Documents