Skip to main content
POST
/
table
/
{tableId}
/
field
/
plan
cURL
curl --request POST \
  --url http://127.0.0.1:3000/api/table/{tableId}/field/plan \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "singleSelect",
  "name": "<string>",
  "unique": true,
  "notNull": true,
  "dbFieldName": "<string>",
  "isLookup": true,
  "isConditionalLookup": true,
  "description": "this is a summary",
  "lookupOptions": {
    "foreignTableId": "<string>",
    "lookupFieldId": "<string>",
    "linkFieldId": "<string>",
    "filter": {}
  },
  "options": {
    "expression": "countall({values})",
    "timeZone": "<string>",
    "formatting": "<unknown>",
    "showAs": {
      "type": "url"
    }
  },
  "aiConfig": {
    "modelKey": "<string>",
    "type": "extraction",
    "sourceFieldId": "<string>",
    "isAutoFill": true,
    "attachPrompt": "<string>"
  },
  "id": "fldxxxxxxxxxxxxxxxx",
  "order": {
    "viewId": "<string>",
    "orderIndex": 123
  }
}
'
{
  "estimateTime": 123,
  "updateCellCount": 123,
  "graph": {
    "nodes": [
      {
        "id": "<string>",
        "label": "<string>",
        "comboId": "<string>"
      }
    ],
    "edges": [
      {
        "source": "<string>",
        "target": "<string>",
        "label": "<string>"
      }
    ],
    "combos": [
      {
        "id": "<string>",
        "label": "<string>"
      }
    ]
  },
  "linkFieldCount": 123
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
tableId
string
required

Body

application/json
​
type
enum<string>
required

The field types supported by teable.

Available options:
singleLineText,
longText,
user,
attachment,
checkbox,
multipleSelect,
singleSelect,
date,
number,
rating,
formula,
rollup,
conditionalRollup,
link,
createdTime,
lastModifiedTime,
createdBy,
lastModifiedBy,
autoNumber,
button
Example:

"singleSelect"

​
name
string
Minimum string length: 1
​
unique
boolean

Whether this field is not unique.

​
notNull
boolean

Whether this field is not null.

​
dbFieldName
string

Field(column) name in backend database. Limitation: 1-63 characters, can only contain letters, numbers and underscore, case sensitive, cannot be duplicated with existing db field name in the table.

Minimum string length: 1
​
isLookup
boolean

Whether this field is lookup field. witch means cellValue and [fieldType] is looked up from the linked table.

​
isConditionalLookup
boolean

Whether this lookup field applies a conditional filter when resolving linked records.

​
description
string | null

The description of the field.

Example:

"this is a summary"

​
lookupOptions
object

The lookup options for field, you need to configure it when isLookup attribute is true or field type is rollup.

​
options
object

The options of the field. The configuration of the field's options depend on the it's specific type.

​
aiConfig

The AI configuration of the field.

​
id
string

The id of the field that start with "fld", followed by exactly 16 alphanumeric characters /^fld[\da-zA-Z]{16}$/. It is sometimes useful to specify an id at creation time

Example:

"fldxxxxxxxxxxxxxxxx"

​
order
object

Response

201 - application/json

Returns the calculation plan for creating the field

​
estimateTime
number
required
​
updateCellCount
number
required
​
graph
object
​
linkFieldCount
number
Last modified on December 10, 2025