Quick Start
API List
- record
- space
- base
- view
- trash
- field
- dashboard
- aggregation
- table
- POSTCreate table
- GETGet table details
- DELDelete table
- GETList tables
- DELPermanently delete table
- PUTUpdate table name
- PUTUpdate table tcon
- PUTUpdate table order
- PUTUpdate table description
- PUTUpdate db table name
- GETGet default view id
- GETGet table permissions
- POSTToggle table index
- POSTGet activated index
- GETGet abnormal indexes
- PATCHRepair table index
- POST
- selection
- plan
- attachments
- user
- auth
- db-connection
- invitation
- share
- notification
- access-token
- import
- export
- pin
- billing
- admin
- usage
- oauth
- plugin
- comment
- organization
- ai
- integrity
Create table
Create a new table in the specified base with customizable fields, views, and initial records. Default configurations will be applied if not specified.
curl --request POST \
--url https://app.teable.io/api/base/%7BbaseId%7D/table/ \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"name":"string","dbTableName":"string","description":"string","icon":"string","fields":[{"type":"singleSelect","name":"Tags","unique":true,"notNull":true,"dbFieldName":"string","isLookup":true,"description":"this is a summary","lookupOptions":{"foreignTableId":"string","lookupFieldId":"string","linkFieldId":"string","filter":{}},"options":{"expression":"countall({values})","timeZone":"string","formatting":{"date":"string","time":"HH:mm","timeZone":"string"},"showAs":{"type":"url"}},"id":"fldxxxxxxxxxxxxxxxx","order":{"viewId":"string","orderIndex":0}}],"views":[{"name":"string","type":"grid","description":"string","order":0,"options":{"rowHeight":"short","frozenColumnCount":0},"sort":{"sortObjs":[{"fieldId":"string","order":"asc"}],"manualSort":true},"filter":{},"group":[{"fieldId":"string","order":"asc"}],"isLocked":true,"shareId":"string","enableShare":true,"shareMeta":{"allowCopy":true,"includeHiddenField":true,"password":"string","includeRecords":true,"submit":{"allow":true,"requireLogin":true}},"columnMeta":{"property1":{"order":0,"width":0,"hidden":true,"statisticFunc":"count"},"property2":{"order":0,"width":0,"hidden":true,"statisticFunc":"count"}},"pluginId":"string"}],"records":[{"fields":{"single line text":"text value"}}],"order":0,"fieldKeyType":"id"}'{
"id": "<string>",
"name": "<string>",
"dbTableName": "<string>",
"description": "<string>",
"icon": "<string>",
"fields": [
{
"id": "<string>",
"name": "Tags",
"type": "singleSelect",
"description": "this is a summary",
"options": {
"expression": "countall({values})",
"timeZone": "<string>",
"formatting": {
"date": "<string>",
"time": "HH:mm",
"timeZone": "<string>"
},
"showAs": {
"type": "url"
}
},
"isLookup": true,
"lookupOptions": {
"foreignTableId": "<string>",
"lookupFieldId": "<string>",
"relationship": "oneOne",
"fkHostTableName": "<string>",
"selfKeyName": "<string>",
"foreignKeyName": "<string>",
"filter": {},
"linkFieldId": "<string>"
},
"notNull": true,
"unique": true,
"isPrimary": true,
"isComputed": true,
"isPending": true,
"hasError": true,
"cellValueType": "string",
"isMultipleCellValue": true,
"dbFieldType": "TEXT",
"dbFieldName": "<string>"
}
],
"views": [
{
"id": "<string>",
"name": "<string>",
"type": "grid",
"description": "<string>",
"order": 123,
"options": {
"rowHeight": "short",
"frozenColumnCount": 1
},
"sort": {
"sortObjs": [
{
"fieldId": "<string>",
"order": "asc"
}
],
"manualSort": true
},
"filter": {},
"group": [
{
"fieldId": "<string>",
"order": "asc"
}
],
"isLocked": true,
"shareId": "<string>",
"enableShare": true,
"shareMeta": {
"allowCopy": true,
"includeHiddenField": true,
"password": "<string>",
"includeRecords": true,
"submit": {
"allow": true,
"requireLogin": true
}
},
"createdBy": "<string>",
"lastModifiedBy": "<string>",
"createdTime": "<string>",
"lastModifiedTime": "<string>",
"columnMeta": {},
"pluginId": "<string>"
}
],
"records": [
{
"id": "<string>",
"name": "<string>",
"fields": {},
"autoNumber": 123,
"createdTime": "<string>",
"lastModifiedTime": "<string>",
"createdBy": "<string>",
"lastModifiedBy": "<string>"
}
],
"order": 123,
"lastModifiedTime": "<string>",
"defaultViewId": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
params for create a table
The name of the table.
1Table name in backend database. Limitation: 1-63 characters, start with letter, can only contain letters, numbers and underscore, case insensitive, cannot be duplicated with existing db table name in the base.
The description of the table.
The emoji icon string of the table.
The fields of the table. If it is empty, 3 fields include SingleLineText, Number, SingleSelect will and 3 empty records be generated by default.
The field types supported by teable.
singleLineText, longText, user, attachment, checkbox, multipleSelect, singleSelect, date, number, duration, rating, formula, rollup, count, link, createdTime, lastModifiedTime, createdBy, lastModifiedBy, autoNumber, button The name of the field. can not be duplicated in the table.
1Whether this field is not unique.
Whether this field is not null.
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.
1Whether this field is lookup field. witch means cellValue and [fieldType] is looked up from the linked table.
The description of the field.
The lookup options for field, you need to configure it when isLookup attribute is true or field type is rollup.
the table this field is linked to
the field in the foreign table that will be displayed as the current field
The id of Linked record field to use for lookup
A filter object used to filter results. It allows complex query conditions based on fields, operators, and values.
The options of the field. The configuration of the field's options depend on the it's specific type.
countall({values}), counta({values}), count({values}), sum({values}), max({values}), min({values}), and({values}), or({values}), xor({values}), array_join({values}), array_unique({values}), array_compact({values}), concatenate({values}) The time zone that should be used to format dates
Different cell value types are determined based on the results of expression parsing, where numbers, dates, and formatting options are provided
the display formatting of the date.
the display formatting of the time.
HH:mm, hh:mm A, None The time zone that should be used to format dates
According to the results of expression parsing to determine different visual effects, where strings, numbers will provide customized "show as"
can display as url, email or phone in string field with a button to perform the corresponding action, start a phone call, send an email, or open a link in a new tab
url, email, phone 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
The views of the table. If it is empty, a grid view will be generated by default.
grid, calendar, kanban, form, gallery, gantt, plugin A filter object used to filter results. It allows complex query conditions based on fields, operators, and values.
A mapping of view IDs to their corresponding column metadata.
Order is a floating number, column will sort by it in the view.
Column width in the view.
If column hidden in the view.
Statistic function of the column in the view.
count, empty, filled, unique, max, min, sum, average, checked, unChecked, percentEmpty, percentFilled, percentUnique, percentChecked, percentUnChecked, earliestDate, latestDate, dateRangeOfDays, dateRangeOfMonths, totalAttachmentSize Define the key type of record.fields[key], You can click "systemInfo" in the field edit box to get fieldId or enter the table design screen with all the field details
id, name Response
Complete table structure data and initial record data.
The id of table.
The name of the table.
Table name in backend database. Limitation: 1-63 characters, start with letter, can only contain letters, numbers and underscore, case insensitive, cannot be duplicated with existing db table name in the base.
The fields of the table.
The id of the field.
The name of the field. can not be duplicated in the table.
The field types supported by teable.
singleLineText, longText, user, attachment, checkbox, multipleSelect, singleSelect, date, number, duration, rating, formula, rollup, count, link, createdTime, lastModifiedTime, createdBy, lastModifiedBy, autoNumber, button The configuration options of the field. The structure of the field's options depend on the field's type.
countall({values}), counta({values}), count({values}), sum({values}), max({values}), min({values}), and({values}), or({values}), xor({values}), array_join({values}), array_unique({values}), array_compact({values}), concatenate({values}) The time zone that should be used to format dates
Different cell value types are determined based on the results of expression parsing, where numbers, dates, and formatting options are provided
the display formatting of the date.
the display formatting of the time.
HH:mm, hh:mm A, None The time zone that should be used to format dates
According to the results of expression parsing to determine different visual effects, where strings, numbers will provide customized "show as"
can display as url, email or phone in string field with a button to perform the corresponding action, start a phone call, send an email, or open a link in a new tab
url, email, phone The cell value type of the field.
string, number, boolean, dateTime The field type of database that cellValue really store.
TEXT, INTEGER, DATETIME, REAL, BLOB, JSON, BOOLEAN 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.
1The description of the field.
Whether this field is lookup field. witch means cellValue and [fieldType] is looked up from the linked table.
field lookup options.
the table this field is linked to
the field in the foreign table that will be displayed as the current field
describe the relationship from this table to the foreign table
oneOne, manyMany, oneMany, manyOne the table name for storing keys, in many-to-many relationships, keys are stored in a separate intermediate table; in other relationships, keys are stored on one side as needed
the name of the field that stores the current table primary key
The name of the field that stores the foreign table primary key
The id of Linked record field to use for lookup
A filter object used to filter results. It allows complex query conditions based on fields, operators, and values.
Whether this field is not null.
Whether this field is not unique.
Whether this field is primary field.
Whether this field is computed field, you can not modify cellValue in computed field.
Whether this field's calculation is pending.
Whether This field has a configuration error. Check the fields referenced by this field's formula or configuration.
Whether this field has multiple cell value.
The views of the table.
grid, calendar, kanban, form, gallery, gantt, plugin A mapping of view IDs to their corresponding column metadata.
Order is a floating number, column will sort by it in the view.
Column width in the view.
If column hidden in the view.
Statistic function of the column in the view.
count, empty, filled, unique, max, min, sum, average, checked, unChecked, percentEmpty, percentFilled, percentUnique, percentChecked, percentUnChecked, earliestDate, latestDate, dateRangeOfDays, dateRangeOfMonths, totalAttachmentSize A filter object used to filter results. It allows complex query conditions based on fields, operators, and values.
The records of the table.
The record id.
Objects with a fields key mapping fieldId or field name to value for that field.
primary field value
Auto number, a unique identifier for each record
Created time, date ISO string (new Date().toISOString).
Last modified time, date ISO string (new Date().toISOString).
Created by, user name
Last modified by, user name
The description of the table.
The emoji icon string of the table.
The last modified time of the table.
The default view id of the table.
curl --request POST \
--url https://app.teable.io/api/base/%7BbaseId%7D/table/ \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"name":"string","dbTableName":"string","description":"string","icon":"string","fields":[{"type":"singleSelect","name":"Tags","unique":true,"notNull":true,"dbFieldName":"string","isLookup":true,"description":"this is a summary","lookupOptions":{"foreignTableId":"string","lookupFieldId":"string","linkFieldId":"string","filter":{}},"options":{"expression":"countall({values})","timeZone":"string","formatting":{"date":"string","time":"HH:mm","timeZone":"string"},"showAs":{"type":"url"}},"id":"fldxxxxxxxxxxxxxxxx","order":{"viewId":"string","orderIndex":0}}],"views":[{"name":"string","type":"grid","description":"string","order":0,"options":{"rowHeight":"short","frozenColumnCount":0},"sort":{"sortObjs":[{"fieldId":"string","order":"asc"}],"manualSort":true},"filter":{},"group":[{"fieldId":"string","order":"asc"}],"isLocked":true,"shareId":"string","enableShare":true,"shareMeta":{"allowCopy":true,"includeHiddenField":true,"password":"string","includeRecords":true,"submit":{"allow":true,"requireLogin":true}},"columnMeta":{"property1":{"order":0,"width":0,"hidden":true,"statisticFunc":"count"},"property2":{"order":0,"width":0,"hidden":true,"statisticFunc":"count"}},"pluginId":"string"}],"records":[{"fields":{"single line text":"text value"}}],"order":0,"fieldKeyType":"id"}'{
"id": "<string>",
"name": "<string>",
"dbTableName": "<string>",
"description": "<string>",
"icon": "<string>",
"fields": [
{
"id": "<string>",
"name": "Tags",
"type": "singleSelect",
"description": "this is a summary",
"options": {
"expression": "countall({values})",
"timeZone": "<string>",
"formatting": {
"date": "<string>",
"time": "HH:mm",
"timeZone": "<string>"
},
"showAs": {
"type": "url"
}
},
"isLookup": true,
"lookupOptions": {
"foreignTableId": "<string>",
"lookupFieldId": "<string>",
"relationship": "oneOne",
"fkHostTableName": "<string>",
"selfKeyName": "<string>",
"foreignKeyName": "<string>",
"filter": {},
"linkFieldId": "<string>"
},
"notNull": true,
"unique": true,
"isPrimary": true,
"isComputed": true,
"isPending": true,
"hasError": true,
"cellValueType": "string",
"isMultipleCellValue": true,
"dbFieldType": "TEXT",
"dbFieldName": "<string>"
}
],
"views": [
{
"id": "<string>",
"name": "<string>",
"type": "grid",
"description": "<string>",
"order": 123,
"options": {
"rowHeight": "short",
"frozenColumnCount": 1
},
"sort": {
"sortObjs": [
{
"fieldId": "<string>",
"order": "asc"
}
],
"manualSort": true
},
"filter": {},
"group": [
{
"fieldId": "<string>",
"order": "asc"
}
],
"isLocked": true,
"shareId": "<string>",
"enableShare": true,
"shareMeta": {
"allowCopy": true,
"includeHiddenField": true,
"password": "<string>",
"includeRecords": true,
"submit": {
"allow": true,
"requireLogin": true
}
},
"createdBy": "<string>",
"lastModifiedBy": "<string>",
"createdTime": "<string>",
"lastModifiedTime": "<string>",
"columnMeta": {},
"pluginId": "<string>"
}
],
"records": [
{
"id": "<string>",
"name": "<string>",
"fields": {},
"autoNumber": 123,
"createdTime": "<string>",
"lastModifiedTime": "<string>",
"createdBy": "<string>",
"lastModifiedBy": "<string>"
}
],
"order": 123,
"lastModifiedTime": "<string>",
"defaultViewId": "<string>"
}