• ✅ 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

• 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.)

• 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

[{id: "ou_xxx"}]

"ou_xxx"

[{name: "Zhang San"}]

1674206443000

"Option Name"

["Option Name"]

["Option 1", "Option 2"]

"Option 1"

{link: "...", text: "..."}

[{file_token: "..."}]

1. First call

   feishu_bitable_app_table_field.list

   to get field

   type

   and

   ui_type

2. Construct the correct format based on the above table or record-values.md
3. Error code

   125406X

   or

   1254015

   → Check field value format

• 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.

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

{
  "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"
      }
    }
  ]
}

• User:

  [{id: "ou_xxx"}]

  (array of objects)
• Date: Millisecond timestamp
• Single Select: String
• Multi Select: Array of strings

{
  "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
    }
  ]
}

• 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

• 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