The base URL for the APITable API request is https://api.apitable.com/fusion/v1/.

Note: https requests must be used, not http requests.

The APITable API follows the RESTful convention as much as possible, i.e. data is added, deleted, and checked via GET, POST, PATCH, and DELETE requests to the space and APITable resources.

The request and response bodies are encoded in JSON format.

The parameter names in JSON use camel naming (e.g. viewId) and are case sensitive.

Way 1: By API token

API Token is the user authentication token.When you send an API request to the APITable server, you must include Authorization: Bearer {Your API Token} in the request header to facilitate the server's authentication of the user's identity.

After successful authentication, this API request will have the same privileges as the user's operations in the APITable interface, i.e. whatever data the user can operate on the interface, this request can also operate on it.

Take the following cURL request as an example.

curl "https://api.apitable.com/fusion/v1/datasheets/{datasheetId}/records" \
  -H "Authorization: Bearer {Your API Token}" \

Its request header includes.

Name	Data Type	Required	Format of Value	Example Value
Authorization	String (string)	Yes	Bearer {Your API Token}	Bearer uskYtInkHozfsMikhh0yfoS

For specific authentication operations, please refer to Quick Start

Way 2: OAuth2 (WIP)

When sending API requests, you need to be aware of several restrictions: frequency restrictions, interface restrictions, usage restrictions.

Frequency limits

The frequency of API requests to the same table from the same user is limited to 5 requests/second.

If the request frequency exceeds the limit, an error "Operation too frequent" will be displayed (error status code 429).

Interface limits

• Get records interface: Get up to 1000 rows of records at a time.

  For example, if you want to fetch 10000 rows of records in bulk, you need to call the Get Records interface at least 10 times.

• Create records interface: Create up to 10 rows of records at a time.

  For example, if you want to create 1000 rows of records in a batch, you need to call the Create Record interface at least 100 times.

• Update records interface: update up to 10 rows of records at a time.

  For example, if you want to update 1000 rows of records in a batch, you need to call the Update Record interface at least 100 times.

• Delete records interface: Delete up to 10 rows of records at a time.

  For example, if you want to delete 1000 rows of records in a batch, you need to call the Delete Record interface at least 100 times.

• Upload attachments interface: only 1 attachment can be uploaded at a time.

  If you need to upload multiple files, you need to call this interface repeatedly.

Usage limits

There are two types of usage limits: one is the limit of API usage; the other is the limit of space resource usage, for details, please refer to pring page.

The maximum capacity of uploading attachments to a single space is 1 GB.

Each time you send an API request, the application returns a business status code and a corresponding message.

If the request fails, you can troubleshoot it based on the status code and error message returned.

HTTP Status Code	Response Message	Business Status Code	Description
200	SUCCESS	200	GET, PATCH, DELETE requests work and return results as expected
201	SUCCESS	200	POST request works and returns results as expected
200	Cannot find the specified datasheet	301	Possible scenarios: 1) The datasheet may have been deleted 2) The user cannot find the datasheet in their own space list
200	Failed to upload attachment	426	Possible scenarios: ① Attachments exceed the 1 GB size limit ② The space has reached its maximum attachment capacity
200	The number of uploaded attachments exceeds the limit	428	Upload attachments can only upload one per call, beyond this error will be reported
200	Operation without node permission	602	Users do not have access rights to the specified datasheet (e.g., manageable, editable, or read-only)
200	(Refer to the specific error message)	400	Parameter exception, data verification exception
401	Authentication failure	401	Possible scenarios: ① API Token is not passed in the request header ② API Token is incorrect
403	Prohibit access	403	Possible scenarios: ① The number of API calls has exceeded the limit ② Unable to get the API usage quota for the space, please try again later
404	Interface does not exist	404	Please check if the request address is correct
429	Operate too often	429	The maximum request frequency for the same table by the same user is 5 times/second
500	SERVER_ERROR (code)	500	Unhandled exceptions for internal services
200	You have exceeded the "Public Beta" limit of 50,000 lines	304	The number of rows in the table has reached the maximum number of rows in a single table, please replace the number of tables as soon as possible to avoid data loss

At present, APITable is open to the interfaces of getting records, creating records, updating records and deleting records.

The data structure of the records is as follows.

Properties	Type	Description	Example values
recordId	string*	record ID	rec1jV9eWxcaB
createdAt	number*	The creation time of the record, in timestamp format	1624960629000
updatedAt	number*	The modification time of this record, in timestamp format	1624964696000
fields	object*	The data of the corresponding field in a record, returned in the format {"field": "value"}	{"status": "in progress"} or `{"created": 1624960629065, "updated": 1624964696235, "category": ["Fixing", "P0"], "issue description": "A small

The data structure of the fields is as follows.

Properties	Type	Description	Example values
id	string*	field ID	fldsRHWJZwFcM
name	string*	field name	Order number
type	string*	Field types, possible values are listed in the section Field Types and Attributes	SingleText
editable	boolean*	Field permissions, i.e. column permissions, true for editable, false for read-only	true
property	object	Field attributes.Different fields have different attributes, see the section Field Types and Attributes for details on the attributes of various fields	{"defaultValue":"To be added"}
isPrimary	boolean	Is the main	true
desc	string	Field descriptions, i.e. column descriptions	This column is the automatic generation of the single number, do not manually modify

Field Types and Attributes

APITable currently has the following field types.

The type of field returned by the interface	The type of the corresponding field
SingleText	single-line text
Text	Multi-line text
SingleSelect	Single choice
MultiSelect	Multiple choice
Number	Number
Currency	Currency
Percent	Percentage
DateTime	Datetime
Attachment	Attachment
Member	Member
Checkbox	Check
Rating	Rating
URL	Website
Phone	A telephone number.
Email	Email
MagicLink	MagicLink
MagicLookUp	MagicLookUp
Formula	Intelligent formula
AutoNumber	Autoincrement number
CreatedTime	Create Timestamp
LastModifiedTime	Modify Timestamp
CreatedBy	Created by
LastModifiedBy	Updated by

The following section describes the properties of each field type in detail.

When the "Get Field" interface is called, the following results are returned for each field type.

SingleText

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "SingleText",
  "property": {
    "defaultValue": ""
  }
}

Field Properties	Data Type	Description
defaultValue	String	When creating a new record, the default value of the corresponding cell of this field, the default is empty

Text

DescriptionNo field properties are available at this time.

SingleSelect

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "SingleSelect",
  "property": {
    "options": [
      {
        "id": "optpTVSGk0R2M",
        "name": "Elevit",
        "color": {
          "name": "indigo_4",
          "value": "#5586FF"
        }
      },
      {
        "id": "optqX2Bw479FG",
        "name": "OAD",
        "color": {
          "name": "blue_4",
          "value": "#55CDFF"
        }
      }
    ]
  }
}

Field Properties	Data Type	Description
options	Object Arrays	List of all available options

Description of the parameters contained under options.

Parameters	Data Type	Description
id	String	option ID
name	String	option name
color	Object	The color of the option, including the name and value of the color

MultiSelect

The field properties are the same as the radio selection.

Number

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Number",
  "property": {
    "defaultValue": "2",
    "precision": 0,
    "commaStyle": ",",
    "symbol": "Square meters"
  }
}

| Field Properties | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | defaultValue | String | The default value for this field when creating a new record, default is empty. | | precision | Number | Indicates the number of decimal places, i.e., the precision of the number.The values are 0 (for integers), 1 (to one decimal place), 2 (to two decimal places), 3 (to three decimal places), 4 (to four decimal places) | | commaStyle | String | Thousand separator, set this property to separate thousands of digits by a comma, such as 1,000.default is empty (optional) | symbol | | symbol | String | numeric units, displayed to the right of the number, default is null (optional) |

Currency

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Currency",
  "property": {
    "defaultValue": "1000.00",
    "precision": 2,
    "symbol": "¥",
    "symbolAlign": "Default"
  }
}

Field Properties	Data Type	Description
defaultValue	String	The default value for this field when creating a new record, the default is null.
precision	Number	Indicates the number of decimal places, i.e., the precision of the number.The values are 0 (for integers), 1 (to one decimal place), 2 (to two decimal places), 3 (to three decimal places), 4 (to four decimal places)
symbol	String	currency symbol, can be any custom character
symbolAlign	String	currency symbol (optional).The default value is Default (the currency unit is immediately to the left of the value), other values are Left (the currency unit is fixed to the left), Right (the currency unit is fixed to the right).

Percent

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Percent",
  "property": {
    "defaultValue": "0.85",
    "precision": 1
  }
}

Field Properties	Data Type	Description
defaultValue	String	The default value of the cell corresponding to this field when creating a new record, the default is empty.
precision	Number	Indicates the number of decimal places to convert the field value to a percentage, i.e., the percentage precision.The values are 0 (for integers), 1 (to one decimal place), 2 (to two decimal places), 3 (to three decimal places), 4 (to four decimal places).For example, if the field value is 0.22, it will be displayed as 22% if the percentage precision is 0. If the percentage precision is 1, it will be displayed as 22.0%

de-duplicate

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "DateTime",
  "property": {
    "format": "YYYY/MM/DD hh:mm",
    "includeTime": true,
    "autoFill": true,
    "timeZone": "Asia/Shanghai",
    "includeTimeZone": true
  }
}

Field Properties	Data Type	Description
format	String	Date format
autoFill	Boolean	Whether to auto-fill the time when creating a new record
includeTime	Boolean	Whether to display the time
timeZone	String	Time zone
includeTimeZone	Boolean	Whether to display time zone

The value of the date field returns timestamp without restricted format.The format information in the field property can be used for formatting, see dayjs format for the meaning.

If you don't want to handle date formatting and want the returned result to be consistent with the view display, you can assign cellFormat to string in the interface request parameters, and all the returned content will be a string.

For available values for timeZone property, please refer to List of Time Zones. Example: Asia/Shanghai。

Attachment

DescriptionNo field properties are available at this time.

Member

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Member",
  "property": {
    "options": [
      {
        "id": "1385370606558318594",
        "name": "Coco",
        "type": "Member",
        "avatar": "https://s1.apitable.com/default/avatar004.jpg"
      }
    ],
    "isMulti": true,
    "shouldSendMsg": true
  }
}

Field Properties	Data Type	Description
options	Object Arrays	Members that have been selected for the current member field
isMulti	Boolean	If or not multiple members can be selected
shouldSendMsg	Boolean	Whether to send an in-site message to a member when it is mentioned in the member column

Description of the parameters contained under options.

| Parameters | Data Type | Description | | ---------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | | id | String | The user's organizational unit id (different from the actual user id) on the current station, hereafter referred to as the member id. e. g.Bob's member id on space A is different from his member id on space B | name | | name | String | member name | | type | String | member type, including Member (for users with physical accounts) and Team (for organizational units on the station, such as departments, groups, etc.) | | avatar | String | URL of the member's avatar |

Checkbox

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Checkbox",
  "property": {
    "icon": "✅"
  }
}

Field Properties	Data Type	Description
icon	String	Iconic representation of the checked value, typically an emoji character

Rating

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Rating",
  "property": {
    "icon": "⭐",
    "max": 5
  }
}

Field Properties	Data Type	Description
icon	String	An icon representation of the rating value, usually an emoji character, such as ⭐ or 🎉
max	Number	The maximum value of the rating, from 1-10

URL

DescriptionNo field properties are available at this time.

Phone

DescriptionNo field properties are available at this time.

Email

DescriptionNo field properties are available at this time.

MagicLink

Two datasheets A and B are connected by a link field, and there will be an association field in A that is associated with B, and a link field in B that is associated with A.This pair of related fields is called a brother field.

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "MagicLink",
  "property": {
    "foreignDatasheetId": "dstgr2YN264s7CXKVs",
    "brotherFieldId": "fldyv9fOeCx8B",
    "limitToViewId": "viwY4B8pmiMoi",
    "limitSingleRecord": true
  }
}

Field Properties	Data Type	Description
foreignDatasheetId	String	Related datasheet ID
brotherFieldId	String	The ID of the brother field in the associated datasheet
limitToViewId	String	Specifies a view of the associated datasheet, limiting the selection to the records under that view
limitSingleRecord	Boolean	Whether to select only a single record

MagicLookUp

The MagicLookUp field is a field attached to a MagicLink field. It is a dynamic computed field, and the cell itself does not store any value.

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "MagicLookUp",
  "property": {
    "relatedLinkFieldId": "fldhBGpM3ylTq",
    "targetFieldId": "fldS2mgS18LE1",
    "rollupFunction": "VALUES",
    "valueType": "Array",
    "entityField": {
      "datasheetId": "dstgr2YN264s7CXKVs",
      "field": {
        "id": "fldS2mgS18LE1",
        "name": "title",
        "type": "SingleText",
        "property": {
          "defaultValue": ""
        },
        "editable": true
      }
    }
  }
}

Field Properties	Data Type	Description
relatedLinkFieldId	String	The associated field ID of the referenced current datasheet
targetFieldId	String	the field ID of the queried field in the associated datasheet
hasError	Boolean	When a lookup dependent associated field is deleted or converted, the referenced value may not be retrieved properly
entityField	Object	The entity fields are finally referenced, excluding MagicLoopUp fields.If an error exists, the entity field may not exist.
rollupFunction	String	aggregate function
valueType	String	Return value type, including String, Boolean, Number, DateTime, Array
format	Object	Returns the result of a number or date formatting operation when the return value is of type Number or DateTime

• Description of the rollupFunction values refer to Lookup Product Manual for the meaning of the parameters.

  Function Name	Return Value Type	Description
  VALUES	array	Original values
  AVERAGE	number	average
  COUNT	number	non-null count
  COUNTA	number	non-null value count
  COUNTALL	number	full count
  SUM	number	Total
  MIN	number/datetime	minimum
  MAX	number/datetime	maximum
  AND	boolean	and operation
  OR	boolean	or operation
  XOR	boolean	eXclusive OR operation
  CONCATENATE	string	concatenate to text
  ARRAYJOIN	string	comma-join
  ARRAYUNIQUE	array	Deduplication
  ARRAYCOMPACT	array	filter all null values

• Description of the parameters contained under entityField.

  Parameters	Data Type	Description
  datasheetId	String	the datasheet ID of the entity field
  field	Object	A Field object other than LookUp, a MagicLookUp can refer to a field of a MagicLookUp type from another datasheet, but ultimately an entity field will exist.

  Note: If you use this field feature in your application, you will need to handle exceptions when a reference error is detected for the field.

• The parameters included under format are described below.

  Parameters	Data Type	Description
  type	String	formatting type DateTime, Number, Percent, Currency
  format	Object	The specific format of the different formatting types

  Formatted as date.

  Parameters	Data Type	Description
  dateFormat	String	Date format, e.g. YYYY/MM/DD
  timeFormat	String	Time format, e.g. hh:mm, HH:mm
  includeTime	Boolean	Whether to display the time
  timeZone	String	Time zone
  includeTimeZone	Boolean	Whether to display time zone

  Formatted as a number or percentage:

  Parameters	Data Type	Description
  precision	Number	numeric precision or percentage precision

  Formatted as currency:

  Parameters	Data Type	Description
  precision	Number	Precision
  symbol	String	currency symbol

Formula

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "Formula",
  "property": {
    "expression": "",
    "valueType": "String",
    "hasError": false
  }
}

Field Properties	Data Type	Description
expression	string*	formula expression
valueType	string(enum)*	Return value type, including String, Boolean, Number, DateTime, Array
hasError	boolean	The calculated value may not be retrieved properly when the relevant field dependent on the formula is deleted or converted.
format	object	When the return value is of type Number or DateTime, it returns a number or date formatted in the same format as the lookup.

Same as magiclookup, exceptions need to be handled when errors are encountered.

AutoNumber

DescriptionNo field properties are available at this time.

CreatedTime

Same as DateTime.

LastModifiedTime

Same as DateTime.

CreatedBy

The member id is at the space level and the creator id is at the account level.

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "CreatedBy",
  "property": {
    "options": [
      {
        "id": "e9cbc839fd1b49be85b1f7b0977047e2",
        "name": "Coco",
        "avatar": "https://s1.apitable.com/default/avatar004.jpg"
      }
    ]
  }
}

Field Properties	Data Type	Description
options	option[]	Members whose fields have been selected by the current member

Description of the parameters contained under options.

Parameters	Data Type	Description
id	string*	user id
name	string*	user nickname
avatar	string*	URL of user avatar

LastModifiedBy

Return a sample fragment of the result (containing only field types and attributes).

{
  "type": "LastModifiedBy",
  "property": {
    "options": [
      {
        "id": "e9cbc839fd1b49be85b1f7b0977047e2",
        "name": "Coco",
        "avatar": "https://s1.apitable.com/default/avatar004.jpg"
      }
    ]
  }
}

Field Properties	Data Type	Description
options	option[]	Current field stored users

Description of the parameters contained under options.

Parameters	Data Type	Description
id	string*	user id
name	string*	user nickname
avatar	string*	URL of user avatar

Currently, only the interface to get views is open in APITable.

Views are different forms of data presentation and are divided into different types such as grid view, kanban view, gallery view, gantt view, etc.Views can be individually set up for filtering, grouping, sorting, etc.

Up to 30 views can be created in a datasheet.

The data structure of the views is as follows.

Properties	Type	Description	Example values
id	string*	view ID	viwpdA8TUBp5r
name	string*	view name	all orders
type	string (enum)*	View type, possible values are Grid, Gallery, Kanban, Gantt	Grid

At the moment, only the interface for creating tables is open for APITable.

Currently the APITable is only open for uploading attachments.

At the moment the APITable only opens the interface to get the list of space stations.

The data structure of space stations is as follows.

Attribute	Type	Description	Example Value
id	string*	space ID	spcX9P2xUcKst
name	string*	space station name	test space station
isAdmin	boolean	whether the current requesting user is the main administrator of this station	true