openapi: 3.0.0 info: title: Base Operations description: >- The official SeaTable API Reference (OpenAPI 3.0). version: "6.2" servers: - url: "https://{server}" variables: server: default: cloud.seatable.io x-readme: explorer-enabled: true metrics-enabled: false proxy-enabled: false # These tags are used by openapi2postmanv2 to generate folder descriptions tags: - name: Base Info description: Get information about a base - name: Rows description: Fetch and manipulate rows inside a base - name: Links description: Fetch and manipulate links inside a base - name: Tables description: Create and manipulate tables inside a base - name: Views description: Create and manipulate views inside a base - name: Columns description: Create and manipulate columns inside a table - name: Big Data description: Manage data in the big data backend - name: Row Comments description: Manage row comments - name: Notifications description: Manage notifications - name: Activities & Logs description: List activities and logs - name: Snapshots description: Manage base snapshots components: # Security scheme definitions (see Authentication) securitySchemes: BaseTokenAuth: type: http scheme: bearer description: This is the [Base-Token](/reference/authentication). # Reusable path, query, header and cookie parameters parameters: #=======================Query parameters=======================# row_id: name: row_id description: Unique id of a row. in: query schema: type: string pattern: ^[A-Za-z0-9\-\_]{22}$ example: YMIviMeERQCUiQhPPqo6Gw required: true page: name: page description: The page number you want to start showing the entries. If no value is provided, 1 will be used. in: query schema: type: integer minimum: 1 example: 1 required: false per_page: name: per_page in: query schema: type: integer minimum: 1 description: The number of results that should be returned. If no value is provided, 25 results will be returned. example: 25 required: false op_type: name: op_type description: >- Type of delete operation that should be listed. Optional. Choose from `delete_row`, `delete_rows`, `delete_table`, and `delete_column`. in: query schema: type: string enum: ["delete_row", "delete_rows", "delete_table", "delete_column"] example: delete_row required: true table_id: name: table_id in: query schema: type: string pattern: "^[A-Za-z0-9]{4}$" description: | The id of the table. The id of a table is unique inside a base and is often used to identify a table. example: "0000" required: true table_name: name: table_name description: | The name of the table to perform the operation on. Alternatively, you can use the `table_id` instead of `table_name`. If using `table_id`, ensure that the key in the request body is replaced accordingly. **Example:** Instead of `table_name: Table1` you can use `table_id: 0000`. in: query schema: type: string example: Table1 required: true view_name: name: view_name in: query schema: type: string required: false description: | The name of the view to perform the operation on. Alternatively, you can use the `view_id` instead of `view_name`. If using `view_id`, ensure that the key in the request body is replaced accordingly. **Example:** Instead of `view_name: Default View` you can use `view_id: 0000`. example: "Default View" order_by: name: order_by in: query schema: type: string required: false description: The name or id of a column that is used to sort the results. example: Likes direction: name: direction in: query schema: type: string enum: ["", "asc", "desc"] default: "" required: false description: The direction of the sort, ascending `asc` or descending `desc`. asc by default. **Works only if start and limit are set, too**. example: "desc" start: name: start in: query schema: type: integer required: false description: Starting position (number) of the returned rows. 0 by default. example: 0 limit: name: limit in: query schema: type: integer minimum: 1 maximum: 1000 required: false description: Number of rows that should be returned. 1000 by default. example: 100 listRowLinkLimit: name: limit in: query schema: type: integer minimum: 1 maximum: 100 required: false description: Limit the number of links you want to receive. 10 by default. example: 10 listRowLinkOffset: name: offset in: query schema: type: integer description: | offset is the beginning number of your query. 0 by default. If your record is linked to multiple records, use e.g. 0 to start querying from the 1st element or e.g. 5 to start querying from the 6th element, etc. **Attention:** The returned list of linked rows is not ordered by its original order on the web interface, but rather by created time (ctime). example: 0 days: name: days description: Number of days to look back for comments. in: query schema: type: integer minimum: 1 example: 7 convert_keys: name: convert_keys in: query schema: type: boolean description: Determines if the columns are returned as their keys (false by default) or their names (true). example: true link_column_key: name: link_column_key in: query schema: type: string minLength: 4 maxLength: 4 required: true description: This is the key of the link column. **Do not** use the `link_id` of the link column here. #=======================Path parameters=======================# base_uuid: name: base_uuid in: path schema: type: string pattern: '^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$' required: true description: The unique identifier of a base. Sometimes also called dtable_uuid. example: 5c264e76-0e5a-448a-9f34-580b551364ca row_id_path: name: row_id in: path schema: type: string pattern: ^[A-Za-z0-9\-\_]{22}$ required: true description: The id of the row. example: Qtf7xPmoRaiFyQPO1aENTj view_name_path: name: view_name in: path schema: type: string required: true description: The name of the view. example: "Default View" comment_id: name: comment_id description: The id of the comment. in: path schema: type: integer minimum: 1 required: true example: 1 notification_id: name: notification_id description: The id of the notification. in: path schema: type: integer minimum: 1 required: true example: 1 op_id_big_data_path: name: op_id description: The id of the big data operation logs. in: path schema: type: integer minimum: 1 required: true example: 1 # Reusable schemas (data models) schemas: row_id: type: string pattern: ^[A-Za-z0-9\-\_]{22}$ description: The id of the row. The id of a row is unique inside a base and is often used to identify one specific row. example: "Qtf7xPmoRaiFyQPO1aENTj" base: type: object description: base (database) in SeaTable properties: _id: type: string pattern: "^[a-zA-Z0-9]{4}$" name: type: string is_header_locked: type: boolean summary_configs: type: object columns: type: array items: type: object rows: type: array items: $ref: "#/components/schemas/row_id" views: type: array items: type: object id_row_map: type: object example: _id: IfcB name: New table is_header_locked: false summary_configs: {} columns: - key: "0000" type: number name: First column editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] - key: 2w6F type: text name: second column editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] - key: 3aAf type: date name: third column editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] rows: [] views: - _id: "0000" name: Default View type: table is_locked: false filter_conjunction: And filters: [] sorts: [] groupbys: [] group_rows: [] groups: [] colorbys: {} hidden_columns: [] rows: [] formula_rows: {} link_rows: {} summaries: {} colors: {} id_row_map: {} sql_query: type: object properties: sql: type: string format: SQL-Query description: SQL-Query to get rows from base. convert_keys: type: boolean description: Determines if the columns are returned as their keys (false by default) or their names (true). parameters: type: array description: Parameters in SQL clause to avoid sql injection. Only needed, if you use `?` in the SQL statement. The parameters will replace the `?` according to their order in the array. items: oneOf: - title: Add a String type: string - title: Add an integer type: integer example: ["Max", 12] server_only: type: boolean description: Show rows from normal and Big Data backend (false by default) or limit the output only to the normal backend (true). example: sql: "SELECT Name, Status FROM Table1 LIMIT 3" convert_keys: true server_only: false required: - sql sql_query_response: type: object properties: metadata: type: array items: type: object results: type: array items: type: object success: type: boolean example: metadata: - key: "0000" name: Name type: text data: default_value: "{creator.id}" enable_fill_default_value: true results: - Name: Box _id: Re7GZaC9Sh-G6RC5zeAn2w - Name: Chocolate _id: BrmPfAWyQaO7PDdAPe7G-w - Name: Flowers _id: ZrFd2YOXQ0eIYJjPbQPGng success: true row: type: object title: Row description: | Pass the set of column names and their values. The column names must be present in your table. Different column types require different ways to input values. For eg: {"Name":"Max", "Age":"21", "Birthday":"2023-02-18", "Checkbox":"true"} example: Name: "Max" Age: 21 Birthday: "2023-02-18" Checkbox: true apply_default: type: boolean description: Use the column default values to populate new rows during creation. False by default. example: false table_name: type: string description: The name of the table to perform the operation on. Alternatively, you can use the `table_id` instead of `table_name`. If using `table_id`, ensure that the key in the request body is replaced accordingly. example: "Table1" table_name_object: type: object properties: table_name: $ref: "#/components/schemas/table_name" required: - table_name column_name: type: string # all chars except [., {}, `ยด] pattern: "^[^.}{`]*$" description: The name of the column. append_row: title: Append a row type: object description: Append a new row at the end of your table. properties: table_name: $ref: "#/components/schemas/table_name" row: $ref: "#/components/schemas/row" apply_default: $ref: "#/components/schemas/apply_default" required: - table_name - row insert_row: title: Insert a row (above or below another row) type: object description: Insert a row below or above another row you specified by its row ID. properties: table_name: $ref: "#/components/schemas/table_name" anchor_row_id: type: string description: "Id of the row the new row should be added next to" example: "Qtf7xPmoRaiFyQPO1aNTjA" row_insert_position: type: string description: Defines if the new row is added below or above anchor row. If this parameter is left blank, `insert_below` is taken as default value. enum: ["", "insert_above", "insert_below"] row: $ref: "#/components/schemas/row" apply_default: $ref: "#/components/schemas/apply_default" required: - table_name - row update_row: type: object description: update Row properties: table_name: $ref: "#/components/schemas/table_name" row_id: $ref: "#/components/schemas/row_id" row: $ref: "#/components/schemas/row" required: - table_name - row - row_id delete_row: type: object description: delete a row properties: table_name: $ref: "#/components/schemas/table_name" row_id: $ref: "#/components/schemas/row_id" required: - table_name - row_id rows: type: object description: object to append multiple rows properties: rows: type: array items: $ref: "#/components/schemas/row" required: - rows rows_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/rows" append_rows: type: object description: add multiple rows properties: table_name: $ref: "#/components/schemas/table_name" rows: type: array description: "Defines the rows which should be added." title: Row Object X items: $ref: "#/components/schemas/row" apply_default: $ref: "#/components/schemas/apply_default" required: - table_name - rows update_rows: type: object description: update multiple rows properties: table_name: $ref: "#/components/schemas/table_name" updates: type: array description: "Defines the rows which should be updated." items: type: object properties: row_id: $ref: "#/components/schemas/row_id" row: $ref: "#/components/schemas/row" required: - table_name - updates delete_rows: type: object description: delete multiple rows properties: table_name: $ref: "#/components/schemas/table_name" row_ids: type: array description: "Defines the rows which should be deleted." items: $ref: "#/components/schemas/row_id" required: - table_name - row_ids table_with_row_ids: type: object properties: table_name: $ref: "#/components/schemas/table_name" row_ids: type: array description: ID of the rows to perform the requested operation. items: $ref: "#/components/schemas/row_id" example: row_ids: - "ZrFd2YOXQ0eIYJjPbQPGng" - "afCU_L5PQLe5AOVwCuGXVw" required: - table_name - row_ids table_id: type: string description: "The id of the table. The id of a table is unique inside a base and is often used to identify a table. In most calls it is possible to replace the `table_id` with the `table_name`." pattern: "^[a-zA-Z0-9]{4}$" example: "0000" link_id: type: string description: Every *link column* has a `key` and `link_id` in the column object. Use [Get Metadata](/reference/getmetadata) to get this `link_id`. Don't use the `key` of the link column. minLength: 4 maxLength: 4 example: jYc7 row_link_create_update_delete: type: object properties: table_id: $ref: "#/components/schemas/table_id" other_table_id: $ref: "#/components/schemas/table_id" link_id: $ref: "#/components/schemas/link_id" other_rows_ids_map: type: object description: Provide an object where each key is a `row_id` and each value is an array of other row_ids. additionalProperties: type: array items: $ref: "#/components/schemas/row_id" required: - link_id - table_id - other_table_id - other_rows_ids_map list_row_links: type: object properties: table_name: $ref: "#/components/schemas/table_name" link_column_name: type: string description: The name of the link-column. Alternatively, you can use `link_column_key` instead. Do not use the `link_id` of the link column here. rows: type: array description: The rows (identified by their ids) you want to get the links for. items: type: object properties: row_id: $ref: "#/components/schemas/row_id" offset: type: integer description: "Offset is the beginning number of your query. If your record is linked to multiple records, use e.g. 0 to start querying from the 1st element or e.g. 5 to start querying from the 6th element, etc. Attention: The returned list of linked rows is not ordered by its original order on the web interface, but rather by created time (ctime). Default is 0." limit: type: integer description: "Specify the maximum number of records to be returned. For example, use 20 to retrieve more than the default 10 records." required: - row_id required: - table_name - link_column_name - rows match_link_columns: type: object description: Match and link rows from two tables based on matching column values. properties: link_id: $ref: "#/components/schemas/link_id" matching_keys: type: array description: "Defines the matching column keys in two tables." items: type: object properties: table1_key: $ref: "#/components/schemas/column_key" table2_key: $ref: "#/components/schemas/column_key" required: - link_id - matching_keys rename_table: type: object description: Rename Table properties: table_name: $ref: "#/components/schemas/table_name" new_table_name: type: string required: - table_name - new_table_name example: new_table_name: New Name delete_table: type: object description: Delete a table properties: table_name: $ref: "#/components/schemas/table_name" required: - table_name duplicate_table: type: object properties: table_name: $ref: "#/components/schemas/table_name" is_duplicate_records: type: boolean required: - table_name - is_duplicate_records example: - is_duplicate_records: true new_view: type: object properties: name: type: string description: Name of the new view. example: "New view" type: type: string description: Type of the view, either normal view or a big data view. The default value is *table*. enum: ["", "table", "archive"] is_locked: type: boolean required: - name - type example: - name: Table1 - type: table - is_locked: false view_name: type: string description: | The name of the view to perform the operation on. Alternatively, you can use the `view_id` instead of `view_name`. If using `view_id`, ensure that the key in the request body is replaced accordingly. **Example:** Instead of `view_name: Default View` you can use `view_id: 0000`. example: "Default View" view_name_only: type: string description: "The new name of the view, if you want to give the view a new name." example: "Default View" is_locked: type: boolean column_key: type: string auto_link_task_id: type: string description: "The ID returned by auto add link task" example: 5c264e76-0e5a-448a-9f34-580b551364ca string_filter_predicate: type: string enum: [ "contains", "does_not_contain", "is", "is_not", "is_empty", "is_not_empty", "is_current_user_ID", ] number_filter_predicate: type: string enum: [ "equal", "not_equal", "less", "greater", "less_or_equal", "greater_or_equal", "is empty", "is not empty", ] collaborator_filter_predicate: type: string enum: [ "has_any_of", "has_all_of", "has_none_of", "is_exactly", "is_empty", "is_not_empty", "include_me", ] date_filter_predicate: type: string enum: [ "is", "is_within", "is_before", "is_after", "is_on_or_before", "is_on_or_after", "is_not", "is_empty", "is_not_empty", ] single-select_filter_predicate: type: string enum: ["is", "is_not", "is_any_of", "is_none_of", "is_empty", "is_not_empty"] multiple-select_filter_predicate: type: string enum: [ "has_any_of", "has_all_of", "has_none_of", "is_exactly", "is_empty", "is_not_empty", ] image_filter_predicate: type: string enum: ["is_empty", "is_not_empty"] email_filter_predicate: type: string enum: [ "contains", "does_not_contain", "is", "is_not", "is_empty", "is_not_empty", ] checkbox_filter_predicate: type: string enum: ["is"] link_filter_predicate: type: string enum: [ "contains", "does_not_contain", "is", "is_not", "is_empty", "is_not_empty", "is_current_user_ID", ] creator_filter_predicate: type: string enum: ["contains", "does_not_contain", "include_me", "is", "is_not"] automatic_filter_predicate: type: string enum: ["contains", "does not contain", "is", "is not"] filter_term: type: string integer_filter_term: type: integer array_of_strings_filter_term: type: array items: type: string boolean_filter_term: type: boolean rating_filter_term: type: integer enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] date_filter_term: type: string pattern: "^[0-9]{4}-((0[1-9])|(1[0-2]))?-(([0-2][0-9])|(3[01]))?$" filter_term_modifier: type: string date_filter_term_modifier: type: string enum: [ "today", "tomorrow", "yesterday", "one_week_ago", "one_week_from_now", "one_month_ago", "one_month_from_now", "number_of_days_ago", "number_of_days_from_now", "exact_date", ] filter_conjunction: type: string enum: ["And", "Or"] description: "If your view has multiple filters you have to decide how the filters should hang together." sort_type: type: string enum: ["up", "down"] sorts: type: array items: type: object properties: column_key: $ref: "#/components/schemas/column_key" sort_type: $ref: "#/components/schemas/sort_type" description: "sorting of your view" groupbys: type: array items: type: object properties: column_key: $ref: "#/components/schemas/column_key" sort_type: $ref: "#/components/schemas/sort_type" description: "grouping of your view" hidden_columns: type: array items: type: string description: "IDs of the columns that should be hidden" filters_text: title: Text type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/string_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_long_text: title: Long Text type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/image_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_number: title: Number type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/number_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_collaborator: title: Collaborator type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/collaborator_filter_predicate" filter_term: $ref: "#/components/schemas/array_of_strings_filter_term" filters_date: title: Date type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/date_filter_predicate" filter_term: $ref: "#/components/schemas/date_filter_term" filter_term_modifier: $ref: "#/components/schemas/date_filter_term_modifier" filters_duration: title: Duration type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/number_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_single_select: title: Single-select type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/single-select_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_multi_select: title: Multiple-select type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/multiple-select_filter_predicate" filter_term: $ref: "#/components/schemas/array_of_strings_filter_term" filters_image: title: Image type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/image_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_file: title: File type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/image_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_email: title: Email type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/email_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_checkbox: title: Checkbox type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/checkbox_filter_predicate" filter_term: $ref: "#/components/schemas/boolean_filter_term" filters_rating: title: Rating type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/number_filter_predicate" filter_term: $ref: "#/components/schemas/rating_filter_term" filters_formula: title: Formula type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/string_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_link: title: Link type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/link_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_link_formula: title: Link Formula type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/link_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_creator: title: Creator type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/creator_filter_predicate" filter_term: $ref: "#/components/schemas/array_of_strings_filter_term" filters_created: title: Created type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/date_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filter_term_modifier: $ref: "#/components/schemas/date_filter_term_modifier" filters_editor: title: Editor type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/creator_filter_predicate" filter_term: $ref: "#/components/schemas/array_of_strings_filter_term" filters_modified: title: Modified type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/date_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filter_term_modifier: $ref: "#/components/schemas/date_filter_term_modifier" filters_automatic: title: Automatic type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/automatic_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_percentage: title: Percentage type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/number_filter_predicate" filter_term: $ref: "#/components/schemas/integer_filter_term" filters_date-time: title: Date-time type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/date_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filter_term_modifier: $ref: "#/components/schemas/date_filter_term_modifier" filters_url: title: URL type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/email_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" filters_geolocation: title: Geolocation type: object properties: column_key: $ref: "#/components/schemas/column_key" filter_predicate: $ref: "#/components/schemas/email_filter_predicate" filter_term: $ref: "#/components/schemas/filter_term" update_view: type: object properties: name: $ref: "#/components/schemas/view_name" is_locked: $ref: "#/components/schemas/is_locked" filters: type: array description: filter of your view items: oneOf: - $ref: "#/components/schemas/filters_text" - $ref: "#/components/schemas/filters_long_text" - $ref: "#/components/schemas/filters_number" - $ref: "#/components/schemas/filters_collaborator" - $ref: "#/components/schemas/filters_date" - $ref: "#/components/schemas/filters_duration" - $ref: "#/components/schemas/filters_single_select" - $ref: "#/components/schemas/filters_multi_select" - $ref: "#/components/schemas/filters_image" - $ref: "#/components/schemas/filters_file" - $ref: "#/components/schemas/filters_email" - $ref: "#/components/schemas/filters_url" - $ref: "#/components/schemas/filters_checkbox" - $ref: "#/components/schemas/filters_rating" - $ref: "#/components/schemas/filters_link" - $ref: "#/components/schemas/filters_link_formula" - $ref: "#/components/schemas/filters_creator" - $ref: "#/components/schemas/filters_created" - $ref: "#/components/schemas/filters_editor" - $ref: "#/components/schemas/filters_modified" - $ref: "#/components/schemas/filters_automatic" - $ref: "#/components/schemas/filters_percentage" - $ref: "#/components/schemas/filters_date-time" - $ref: "#/components/schemas/filters_geolocation" filter_conjunction: $ref: "#/components/schemas/filter_conjunction" sorts: $ref: "#/components/schemas/sorts" groupbys: $ref: "#/components/schemas/groupbys" hidden_columns: $ref: "#/components/schemas/hidden_columns" update_comment: type: object properties: options: type: object properties: comment: type: string resolved: type: string enum: ["0", "1"] required: - options - comment - resolved anchor_column: description: Give the name or the key of a column after you would like to add this new column. If you leave this empty, the new column will be created at the end. type: string # text column text_column: title: Text type: object description: Add a text column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["text"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type text_column_with_table_name: title: Text allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/text_column" # long text (no column_data) long_text_column: title: Long text type: object description: Add a long text column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["long-text"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type long_text_column_with_table_name: title: Long text allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/long_text_column" # number column (with column_data) number_column: title: Number / Currency / Percentage type: object description: Add a number column and define if the column should contain numbers, currencies or percentage values. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["number"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/number_column_format" required: - column_name - column_type number_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/number_column" number_column_format: description: Specify the number column. type: object properties: format: type: string enum: ["", "number", "percent", "dollar", "euro", "yuan"] description: Choose what kind of number this column should contain. decimal: type: string enum: ["dot", "comma"] description: | Choose how decimals are shown: 1.00 or 1,00 thousands: type: string enum: ["", "no", "space", "comma"] description: | Choose how bigger numbers are displayed. Eg: no: 1000000 dot: 1.000.000 comma: 1,000,000 # collaborator column (no column_data) collaborator_column: title: Collaborator type: object description: Add a collaborator column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["collaborator"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type collaborator_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/collaborator_column" # date column (with column_data) date_column: title: Date type: object description: Add a date column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["date"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/date_column_format" required: - column_name - column_type date_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/date_column" date_column_format: description: Specify the date column. type: object properties: format: type: string enum: [ "", "YYYY-MM-DD", "YYYY-MM-DD HH:mm", "M/D/YYYY", "M/D/YYYY HH:mm", "DD/MM/YYYY", "DD/MM/YYYY HH:mm", "DD.MM.YYYY", "DD.MM.YYYY HH:mm", ] description: | Choose how date values are displayed. Eg: YYYY-MM-DD: ISO-Format M/D/YYYY: US-Format DD/MM/YYYY: European-Format DD.MM.YYYY: German-Format HH:mm: Accurate to minute # duration column (with column_data) duration_column: title: Duration type: object description: Add a duration column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["duration"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/duration_column_format" required: - column_name - column_type duration_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/duration_column" duration_column_format: description: Specify the duration column. type: object properties: format: type: string enum: ["duration"] duration_format: type: string enum: ["", "h:mm", "h:mm:ss"] description: | Choose how to save the duration values. Eg: h:mm: hours and minutes (1:23) h:mm:ss: hours, minutes and seconds (1:23:24) # single select (with column_data) single_select_column: title: Single-select type: object description: Add a single-select column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["single-select"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/select_column_format" required: - column_name - column_type single_select_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/single_select_column" select_column_format: description: Specify the single-select column. type: object properties: options: type: array items: type: object description: Define one or many options for this column properties: id: type: string description: Select any unique id. pattern: "^([A-Za-z0-9]){6}$" name: type: string description: The name of your option. color: type: string description: select your color-code for the background. pattern: "^#[A-Fa-f0-9]{6}$" example: #F4667C textColor: type: string description: select your color-code for the text. pattern: "^#[A-Fa-f0-9]{6}$" example: #FFFFFF borderColor: type: string description: select your color-code for the text. pattern: "^#[A-Fa-f0-9]{6}$" example: #7BC0D6 # multiple select (with column_data) multiple_select_column: title: Multiple-select type: object description: Add a multiple-select column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["multiple-select"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/select_column_format" required: - column_name - column_type multiple_select_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/multiple_select_column" # image column (no column_data) image_column: title: Image type: object description: Add an image column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["image"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type image_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/image_column" # file column (no column_data) file_column: title: File type: object description: Add a file column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["file"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type file_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/file_column" # email column (no column_data) email_column: title: Email type: object description: Add an email column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["email"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type email_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/email_column" url_column: title: Url type: object description: Add an url column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["url"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type url_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/url_column" checkbox_column: title: Checkbox type: object description: Add a checkbox column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["checkbox"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type checkbox_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/checkbox_column" geo_column_format: description: Specify the geolocation column. type: object properties: geo_format: type: string enum: ["lng_lat", "country_region"] geolocation_column: title: Geolocation type: object description: Add a geolocation column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["geolocation"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/geo_column_format" required: - column_name - column_type geolocation_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/geolocation_column" rating_column: title: Rating type: object description: Add a rating column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["rate"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/rating_column_format" required: - column_name - column_type - column_data rating_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/rating_column" rating_column_format: description: Specify the rating column. type: object properties: rate_max_number: type: integer minimum: 0 maximum: 10 example: 5 rate_style_color: type: string pattern: ^#[A-Fa-f0-9]{6}$ example: "#EB00B1" rate_style_type: type: string enum: [ "dtable-icon-rate", "dtable-icon-like", "dtable-icon-praise", "dtable-icon-flag", ] example: dtable-icon-rate formula_column: title: Formula type: object description: Add a formula column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["formula"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/formula_column_format" required: - column_name - column_type - column_data formula_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/formula_column" formula_column_format: description: Specify the formula column. type: object properties: formula: type: string description: The formula of this column. example: dateAdd({Date}, 1, 'year' required: - formula link_column: title: Link column type: object description: Add a link column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["link"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/link_column_format" required: - column_name - column_type - column_data link_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/link_column" link_column_format: description: Specify the link column. type: object properties: table: type: string description: Name of this table. other_table: type: string description: Name of the other table. required: - table - other_table link_formula_column: title: Link-Formula column type: object description: Add a link-formula column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["link-formula"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: oneOf: - $ref: "#/components/schemas/link_formula_column_countLinks_format" - $ref: "#/components/schemas/link_formula_column_lookup_format" - $ref: "#/components/schemas/link_formula_column_rollup_format" - $ref: "#/components/schemas/link_formula_column_findmax_format" - $ref: "#/components/schemas/link_formula_column_findmin_format" required: - column_name - column_type - column_data link_formula_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/link_formula_column" link_formula_column_countLinks_format: title: countlinks description: Specify the link-formula column. type: object properties: formula: type: string description: | The formula of this column. enum: ["count_links"] example: count_links link_column: type: string description: Name of the link column. required: - formula - link_column link_formula_column_lookup_format: title: lookup description: Specify the link-formula column. type: object properties: formula: type: string description: | The formula of this column. enum: ["lookup"] link_column: type: string description: Name of the link column. level1_linked_column: type: string description: Name of the column in the linked table to look up. level2_linked_column: type: string description: Name of the column in the linked table linked by level1_linked_column to look up. The type of level1_linked_column should be 'link'. required: - formula - link_column - level1_linked_column link_formula_column_rollup_format: title: rollup description: Specify the link-formula column. type: object properties: formula: type: string description: | The formula of this column. enum: ["rollup"] example: rollup link_column: type: string description: Name of the link column. summary_column: type: string description: The column in the linked table to be summarized. summary_method: type: string enum: ["average", "concatenate", "max", "min", "sum"] required: - formula - link_column - summary_column - summary_method link_formula_column_findmin_format: title: findmin description: Specify the link-formula column. type: object properties: formula: type: string description: | The formula of this column. enum: ["findmin"] example: findmin link_column: type: string description: Name of the link column. searched_column: type: string description: The column in the linked table to look up. comparison_column: type: string description: The column in the linked table to be evaluated. required: - formula - link_column - searched_column - comparison_column link_formula_column_findmax_format: title: findmax description: Specify the link-formula column. type: object properties: formula: type: string description: | The formula of this column. enum: ["findmax"] example: findmax link_column: type: string description: Name of the link column. searched_column: type: string description: The column in the linked table to look up. comparison_column: type: string description: The column in the linked table to be evaluated. required: - formula - link_column - searched_column - comparison_column creator_column: title: Creator type: object description: Add a creator column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["creator"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type creator_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/creator_column" ctime_column: title: Creation time type: object description: Add a creation time column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["ctime"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type ctime_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/ctime_column" last_modifier_column: title: Last Modifier type: object description: Add a last modifier column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["last-modifier"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type last_modifier_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/last_modifier_column" mtime_column: title: Last modification time type: object description: Add a last modification time column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["mtime"] anchor_column: $ref: "#/components/schemas/anchor_column" required: - column_name - column_type mtime_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/mtime_column" autonumber_column: title: Auto number type: object description: Add an auto number column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["auto-number"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/autonumber_column_format" required: - column_name - column_type autonumber_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/autonumber_column" autonumber_column_format: description: >- Specify the auto number column. The `format` field defines the number pattern (e.g. "0000" for 4 digits). Use `prefix_type` to add a prefix: "string" for a custom text prefix, or "date" for a date-based prefix. type: object properties: format: type: string description: The number format pattern. example: "0000" digits: type: integer description: Number of digits (must match the zeros in `format`). example: 4 prefix_type: type: string description: Type of prefix โ€” "string" for a custom prefix, "date" for a date-based prefix (YYYYMMDD). enum: ["string", "date"] example: "string" prefix: type: string description: The prefix value (only used when `prefix_type` is "string"). example: "ID-" required: - format - digits button_column: title: Button column type: object description: Add a button column. properties: column_name: $ref: "#/components/schemas/column_name" column_type: type: string enum: ["button"] anchor_column: $ref: "#/components/schemas/anchor_column" column_data: $ref: "#/components/schemas/button_column_format" required: - column_name - column_type - column_data button_column_with_table_name: allOf: - $ref: "#/components/schemas/table_name_object" - $ref: "#/components/schemas/button_column" button_column_format: description: Specify the button column. type: object properties: button_type: type: string enum: [ "", "run_script", "send_email", "copy_row_to_another_table", "modify_row", ] button_name: type: string button_color: type: string pattern: ^#[A-Fa-f0-9]{6}$ table_id: type: string description: id of the target table, if `copy_row_to_another_table` is selected. script_id: type: string selected_columns: type: array items: type: object properties: key: type: string value: type: string required: - button_type - button_name - button_color rename_column: title: Rename Column type: object properties: op_type: type: string enum: [rename_column] table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" new_column_name: type: string example: "New Oranges" required: - op_type - table_name - column - new_column_name resize_column: title: Resize Column type: object properties: op_type: type: string enum: ["resize_column"] table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" new_column_width: type: integer example: 400 required: - op_type - table_name - column - new_column_width freeze_unfreeze_column: title: Freeze/Unfreeze Column type: object properties: op_type: type: string enum: ["freeze_column"] table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" frozen: type: boolean required: - op_type - table_name - column - frozen move_column: title: Move Column type: object properties: op_type: type: string enum: ["move_column"] table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" target_column: type: string example: "Likes" required: - op_type - table_name - column - target_column update_column_type: title: Update Column Type type: object properties: op_type: type: string enum: ["modify_column_type"] table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" new_column_type: type: string example: "number" column_data: type: object required: - op_type - table_name - column - new_column_type update_column: oneOf: - $ref: "#/components/schemas/update_column_type" - $ref: "#/components/schemas/rename_column" - $ref: "#/components/schemas/resize_column" - $ref: "#/components/schemas/move_column" - $ref: "#/components/schemas/freeze_unfreeze_column" delete_column: type: object properties: table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" required: - table_name - column add_single__multiple_select_options: type: object properties: table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" options: type: array items: type: object properties: name: type: string example: "Option 1" color: type: string example: "#FF8000" textColor: type: string example: "#1DDD1D" update_single__multiple_select_options: type: object properties: table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" options: type: array items: type: object properties: id: type: string example: "119376" color: type: string example: "#4ECCCB" textColor: type: string example: "#1DDD1D" name: type: string example: "Finished" required: - id return_options: type: boolean delete_select_options: type: object properties: table_name: $ref: "#/components/schemas/table_name" column: $ref: "#/components/schemas/column_name" option_names: type: array items: type: string description: Name of the select options required: - table_name - column - option_names insert_rows_into_big_data: type: object properties: table_name: $ref: "#/components/schemas/table_name" rows: type: array items: $ref: "#/components/schemas/row" required: - table_name - rows archive-view: type: object properties: table_name: $ref: "#/components/schemas/table_name" view_name: $ref: "#/components/schemas/view_name" required: - table_name - view_name create_row_comment: type: object properties: comment: type: string example: "Let's discuss this tomorrow" generate_snapshot: type: object properties: dtable_name: type: string example: Example paths: /api-gateway/api/v2/dtables/{base_uuid}/metadata/: get: tags: - Base Info summary: Get Metadata operationId: getMetadata description: Get the complete metadata of a base with all tables, columns and views and settings. The metadata does not contain any data. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: metadata: tables: - _id: "0000" name: Table1 columns: - key: "0000" name: Name type: text width: 200 editable: true resizable: true - key: Cw35 type: link name: Link editable: true width: 141 resizable: true draggable: true data: display_column_key: "0000" table_id: "0000" other_table_id: "0000" is_internal_link: true is_multiple: true is_row_from_view: false other_view_id: "0000" link_id: 7V2M permission_type: "" permitted_users: [] - key: BydO type: date name: Date editable: true width: 200 resizable: true draggable: true data: format: YYYY-MM-DD permission_type: "" permitted_users: [] views: - _id: "0000" name: Default View type: table is_locked: false rows: [] formula_rows: {} summaries: [] filter_conjunction: And filters: [] sorts: [] hidden_columns: [] groupbys: [] groups: [] version: 482 format_version: 7 settings: securities: table_settings: can_copy: false can_export: false can_print: false share_user_settings: can_copy: false can_export: false can_print: false "403": description: Forbidden โ€” missing or invalid base token content: application/json: schema: type: object example: error_message: invalid token /api-gateway/api/v2/dtables/{base_uuid}/related-users/: get: tags: - Base Info summary: List Collaborators operationId: listCollaborators description: List all collaborators of a base with name, email address and avatar. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: user_list: - email: 244b430060f54bb4afa2c2cb7369d244@auth.local name: Ginger Ale contact_email: gingerale@example.com avatar_url: https://cloud.seatable.io/media/avatars/default.png - email: 8cb2a6da65687600f42905bf1647fd3f@auth.local name: Jasmin Tee contact_email: jasmintee@example.com avatar_url: https://cloud.seatable.io/media/avatars/default.png # Rows /api-gateway/api/v2/dtables/{base_uuid}/sql/: post: tags: - Rows summary: Query SeaTable with SQL operationId: querySQL description: | This is the **recommended endpoint** for reading and modifying data in SeaTable. It supports `SELECT`, `INSERT`, `UPDATE`, and `DELETE` โ€” giving you full access to filter, sort, group, join, and aggregate data in a single request. It works seamlessly across both normal and big data storage and returns column metadata alongside the results. SQL syntax is case insensitive and most common functions work as expected โ€” including `now()`, `round()`, `upper()`, `trim()`, `abs()`, and many more. Some functions use SeaTable-specific names (e.g. `mid()` instead of `SUBSTR()`, `concatenate()` instead of `CONCAT()`). See the [function reference](https://developer.seatable.com/sql/functions/) for the complete list and a MySQL/MariaDB equivalents table. **Example queries** for a table *Contacts* with columns *Name*, *Age*, *City*: - `SELECT * FROM Contacts WHERE Age >= 18 ORDER BY Name LIMIT 100` - `SELECT City, COUNT(*), AVG(Age) FROM Contacts GROUP BY City` - `SELECT DISTINCT City FROM Contacts` - `UPDATE Contacts SET City = 'Berlin' WHERE Name = 'Alice'` - `DELETE FROM Contacts WHERE Age < 18` - `SELECT * FROM Contacts WHERE Name = ? AND Age = ?` (parameterized query) For the complete SQL reference, see the [SeaTable Developer Manual](https://developer.seatable.com/sql/): - [SELECT](https://developer.seatable.com/sql/select/) โ€” retrieve, filter, sort, group, and join rows - [INSERT](https://developer.seatable.com/sql/insert/) โ€” append rows (big data storage only) - [UPDATE](https://developer.seatable.com/sql/update/) โ€” modify rows - [DELETE](https://developer.seatable.com/sql/delete/) โ€” remove rows - [Functions](https://developer.seatable.com/sql/functions/) โ€” all supported functions and MySQL/MariaDB equivalents - [Limitations](https://developer.seatable.com/sql/limitations/) โ€” column writability, NULL handling, list types > ๐Ÿ“˜ Avoid SQL injection > > Use `?` placeholders in your SQL statement and pass the actual values via the `parameters` array. This protects against SQL injection. Example: `SELECT * FROM T WHERE Name = ? AND Age = ?` with `parameters: ["Alice", 30]`. > โ— Limits > > - **Default:** 100 rows. **Maximum:** 10,000 rows. Use `LIMIT` and `OFFSET` to paginate. > - **Link columns** return a maximum of 50 linked records per row. > - **INSERT** only works with bases that have big data storage enabled. > ๐Ÿšง Key restrictions > > - Functions and expressions are **not supported** in `UPDATE SET` or `INSERT VALUES` โ€” only constant values are allowed. > - `JOIN` keyword is not supported โ€” use implicit joins: `SELECT ... FROM T1, T2 WHERE T1.col = T2.col`. > - Subqueries and `UNION` are not supported. > - `SELECT` uses column **names** by default. Set `convert_keys` to `false` to get column keys instead. requestBody: content: application/json: schema: $ref: "#/components/schemas/sql_query" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/sql_query_response" "400": description: Bad Request โ€” invalid SQL syntax or non-existing table. content: application/json: schema: type: object properties: error_message: type: string example: "no such table: nonexistent_table" /api-gateway/api/v2/dtables/{base_uuid}/rows/: get: tags: - Rows summary: List Rows operationId: listRows description: | Returns a list of rows contained in a table (or in a view if provided). The usage of a view in SeaTable could be much more convenient than the usage of the complex SQL-syntax of the [SQL query endpoint](/reference/querysql). > ๐Ÿ‘ Big Data support added > > Since Version 4.4 this endpoint also supports the big data backend. Every row consists of the columns, you defined in your base but also *hidden* informations like `_id`, `_mtime`, `_ctime`, `_creator` and so on. Get more details about these information in the [Models](/reference/models) area. > ๐Ÿ“˜ Hidden Columns > > If no view is selected, all columns (even hidden one) are returned. If a view is selected, only the visible columns of that view are returned with the request. > ๐Ÿ“˜ Link Columns > > From version 5.3 onward, the link column of a row returns a maximum of 50 records. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/table_name" - $ref: "#/components/parameters/view_name" - $ref: "#/components/parameters/start" - $ref: "#/components/parameters/limit" - $ref: "#/components/parameters/convert_keys" responses: "200": description: OK content: application/json: schema: type: object example: rows: - _id: Bko1e60YT-egit2SljWSZA _mtime: "2021-03-10T16:06:48.981+00:00" Name: Second new row link: [ { "display_value": "1", "row_id": "XzdZfL2oS-aILnhfagTWEg", }, ] - _id: RzeUwIhFSp-iNi81-bZvpA _mtime: "2021-03-10T16:11:11.176+00:00" Name: Matcha link: [] post: tags: - Rows summary: Append Row(s) operationId: appendRows description: |- Append multiple rows to a table. Define the column:values pairs of each column in the [rows object](/reference/models). > ๐Ÿšง Column names only > > This endpoint always expects **column names** (e.g. `Name`) in the row object, not internal column keys (e.g. `0000`). The `convert_keys` parameter is not supported. Unknown keys are silently ignored without error. requestBody: content: application/json: schema: $ref: "#/components/schemas/append_rows" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object properties: inserted_row_count: type: integer row_ids: type: array items: type: object first_row: type: object example: inserted_row_count: 3 row_ids: - _id: Bko1e60YT-egit2SljWSZA - _id: RzeUwIhFSp-iNi81-bZvpA first_row: "0000": Second new row _id: Bko1e60YT-egit2SljWSZA _creator: 123456786569491ba42905bf1647fd3f@auth.local _last_modifier: 123456786569491ba42905bf1647fd3f@auth.local put: tags: - Rows summary: Update Row(s) operationId: updateRow description: | Change the values in one or multiple existing row(s) by defining the new values for necessary columns in the row object. Both SeaTable backends are supported. > ๐Ÿ“˜ Structure of the row object > > The row object contains key:value pairs with the column name as key and the desired values. Check the page [Models](/reference/models) to get a better understanding of the row object. > ๐Ÿšง Column names only > > This endpoint always expects **column names** (e.g. `Name`) in the row object, not internal column keys (e.g. `0000`). The `convert_keys` parameter is not supported. Unknown keys are silently ignored without error. requestBody: content: application/json: schema: $ref: "#/components/schemas/update_rows" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true delete: tags: - Rows summary: Delete Row(s) operationId: deleteRow description: | Deletes one or multiple rows from the table, identified by its row id no matter if the row is stored in big data or normal backend. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" requestBody: content: application/json: schema: $ref: "#/components/schemas/delete_rows" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/rows/{row_id}/: get: tags: - Rows summary: Get Row operationId: getRow description: Get the values of one row with all columns and values, according to the row id provided. Depending on `convert_keys` the response will contain the column names or the column keys. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/row_id_path" - $ref: "#/components/parameters/table_name" - $ref: "#/components/parameters/convert_keys" responses: "200": description: OK content: application/json: schema: type: object properties: _id: type: string _mtime: type: string Name: type: string Date: type: string Content: type: string link: type: array items: type: object example: _id: Qtf7xPmoRaiFyQPO1aENTj _mtime: "2021-03-10T16:19:31.761+00:00" Name: NewName Date: "2020-08-01" Content: "111" link: [] "403": description: Forbidden โ€” missing or invalid base token content: application/json: schema: type: object example: error_message: invalid token "404": description: Not Found content: application/json: schema: type: object example: error_message: row _id not exits /api-gateway/api/v2/dtables/{base_uuid}/lock-rows/: put: tags: - Rows summary: Lock Rows operationId: lockRows description: | Locks one or more rows. It is ok to include rows that were already locked. Rows in big data backend can not be locked. > ๐Ÿ“˜ Advanced feature > > Lock rows is an advanced feature in SeaTable and only available for [enterprise subscriptions](https://seatable.com/prices/). requestBody: content: application/json: schema: $ref: "#/components/schemas/table_with_row_ids" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/unlock-rows/: put: tags: - Rows summary: Unlock Rows operationId: unlockRows description: | Use this API request to unlock one or more locked rows. As this request makes sure that all the mentioned rows are unlocked, it's OK to include rows that were not locked. requestBody: content: application/json: schema: $ref: "#/components/schemas/table_with_row_ids" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true # Links /api-gateway/api/v2/dtables/{base_uuid}/query-links/: post: tags: - Links summary: List Row Links operationId: listRowLinks description: | When you have a "Link to other records" column in your table and you have created some links to the current or another table, you can use this request to query each row's linked records' IDs and display values. By default, it returns 10 records per row. To query more records, please set the "offset" and "limit" values for a row in the rows parameter. > ๐Ÿ“˜ id or name > > In the request body you can as keys either: > - `table_id` or `table_name` > - `link_column_key` or `link_column_name` To get more information about each linked record, retrieve their `row_id` and use the [Query SeaTable with SQL](/reference/querysql) request, for example: ``` SELECT * FROM Table1 WHERE _id IN (row_id1, row_id2, ...); ``` requestBody: content: application/json: schema: $ref: "#/components/schemas/list_row_links" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: Qtf7xPmoRaiFyQPO1aENTj: - row_id: G5rbgqudTKKfAm1-cjnjbQ display_value: Orson /api-gateway/api/v2/dtables/{base_uuid}/links/: post: tags: - Links summary: Create Row Link(s) operationId: createRowLink description: | Creates multiple links between one column and many others (1:n relation). It is not possible to create a link twice. This will result in an error. Here is an example, how the body with `other_rows_ids_map` can look like: ``` "other_rows_ids_map": { "ZEZuAL_8QS6p0tJ2vyKgKw": ["Qtf7xPmoRaiFyQPO1aENTj", "PSnPPXD6SranQwA4_MhN8A"], "PCFS8gY9R8yok5ZZOSqbHg": ["WO2IlomAQVeACVVg8liOMA", "PSnPPXD6SranQwA4_MhN8A"] } ``` requestBody: content: application/json: schema: $ref: "#/components/schemas/row_link_create_update_delete" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true put: tags: - Links summary: Update Row Link(s) operationId: updateRowLink description: | Updates the link(s) between one column and many others (1:n relation). Existing links will be removed and replaced with this new mapping. requestBody: content: application/json: schema: $ref: "#/components/schemas/row_link_create_update_delete" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true delete: tags: - Links summary: Delete Row Link(s) operationId: deleteRowLink description: Deletes one or multiple links between two rows. Only the links between the row_ids mentioned in the mapping, will be removed. Other links will stay and not be touched. requestBody: content: application/json: schema: $ref: "#/components/schemas/row_link_create_update_delete" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: deleted_links_count: 1 /api-gateway/api/v2/dtables/{base_uuid}/auto-links/: post: tags: - Links summary: Auto Links operationId: autoLinks description: | Automatically create link relationships. The caller needs to create a link column before calling the API, supporting both archived and unarchived data. It will return a task ID, by querying which you can get the status of the link creation in the backend within 5 minutes. The matched data in the link column in the 2 tables must have the similar data structure (not same column type). For example, the text column can match email, auto-number or url type column, and so on. Currently, there are a few restrictions: - Formula and link-formula columns are not supported as matching columns - Single-select columns cannot be matched with text columns. requestBody: content: application/json: schema: $ref: "#/components/schemas/match_link_columns" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: task_id: 19b3c803-051e-4c16-bf4d-682d24f7981e /api-gateway/api/v2/dtables/{base_uuid}/auto-link-task/: get: tags: - Links summary: Auto Link task operationId: autoLinkTask description: | Query the status of auto add links task. There are 3 different status: - success - failed - running requestBody: content: application/json: schema: $ref: "#/components/schemas/auto_link_task_id" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: status: success # Tables /api-gateway/api/v2/dtables/{base_uuid}/tables/: post: tags: - Tables summary: Create Table operationId: createTable description: | Creates a new table in a base. Optionally, you can already add some columns to the base. > ๐Ÿ“˜ The first column is special > > Please be aware, that the first column can only be the column type `text`, `number`, `date`, `single select`, `formula` and `autonumber`. requestBody: content: application/json: schema: type: object properties: table_name: $ref: "#/components/schemas/table_name" columns: type: array items: oneOf: - $ref: "#/components/schemas/text_column" - $ref: "#/components/schemas/long_text_column" - $ref: "#/components/schemas/number_column" - $ref: "#/components/schemas/collaborator_column" - $ref: "#/components/schemas/date_column" - $ref: "#/components/schemas/duration_column" - $ref: "#/components/schemas/single_select_column" - $ref: "#/components/schemas/multiple_select_column" - $ref: "#/components/schemas/image_column" - $ref: "#/components/schemas/file_column" - $ref: "#/components/schemas/email_column" - $ref: "#/components/schemas/url_column" - $ref: "#/components/schemas/checkbox_column" - $ref: "#/components/schemas/rating_column" - $ref: "#/components/schemas/formula_column" - $ref: "#/components/schemas/link_column" - $ref: "#/components/schemas/link_formula_column" - $ref: "#/components/schemas/creator_column" - $ref: "#/components/schemas/ctime_column" - $ref: "#/components/schemas/last_modifier_column" - $ref: "#/components/schemas/mtime_column" - $ref: "#/components/schemas/autonumber_column" - $ref: "#/components/schemas/button_column" required: - table_name - columns security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/base" put: tags: - Tables summary: Rename Table operationId: renameTable description: Rename a table by providing its original `table_name` and the desired `new_table_name`. requestBody: content: application/json: schema: $ref: "#/components/schemas/rename_table" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true delete: tags: - Tables summary: Delete Table operationId: deleteTable description: Delete an existing table identified by its name. requestBody: content: application/json: schema: $ref: "#/components/schemas/delete_table" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/tables/duplicate-table/: post: tags: - Tables summary: Duplicate Table operationId: duplicateTable description: | Duplicate an existing table in your base with or without the existing data in it. > ๐Ÿšง Rename the table in a second step > > If you duplicate one table, the name of this new table will always be the same like the original one plus the appendix **(copy)**. To rename the table, you will need another call. requestBody: content: application/json: schema: $ref: "#/components/schemas/duplicate_table" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object properties: _id: type: string name: type: string columns: type: array items: type: object rows: type: array items: type: object id_row_map: type: object views: type: array items: type: object example: _id: oW2Q name: Appointments columns: - key: "0000" type: text name: Name editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] description: null rows: [] id_row_map: {} views: - _id: "0000" name: Default View type: table is_locked: false rows: [] formula_rows: {} summaries: [] filter_conjunction: And filters: [] sorts: [] hidden_columns: [] groupbys: [] groups: [] # Views /api-gateway/api/v2/dtables/{base_uuid}/views/: get: tags: - Views summary: List Views operationId: listViews description: List all the views and their settings in a table. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/table_name" responses: "200": description: OK content: application/json: schema: type: object example: views: - _id: "0000" name: Default View type: table is_locked: false rows: [] formula_rows: {} summaries: [] filter_conjunction: And sorts: [] filters: [] hidden_columns: [] groupbys: [] group_rows: [] groups: [] post: tags: - Views summary: Create View operationId: createView description: Create a new view in the current table. In the **request body**, use `name` for the name of the new view. After creating the new view, use the request [Update View](/reference/updateview) to further define your view. requestBody: content: application/json: schema: $ref: "#/components/schemas/new_view" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/table_name" responses: "200": description: OK content: application/json: schema: type: object properties: _id: type: string name: type: string type: type: string is_locked: type: boolean filter_conjunction: type: string filters: type: array items: type: object sorts: type: array items: type: object groupbys: type: array items: type: object group_rows: type: array items: type: object groups: type: array items: type: object colorbys: type: object hidden_columns: type: array items: type: object rows: type: array items: type: object formula_rows: type: object link_rows: type: object summaries: type: object colors: type: object example: _id: PeJE name: New view type: table is_locked: false filter_conjunction: And filters: [] sorts: [] groupbys: [] group_rows: [] groups: [] colorbys: {} hidden_columns: [] rows: [] formula_rows: {} link_rows: {} summaries: {} colors: {} "400": description: A view with this name already exists in the table. content: application/json: example: error_msg: params invalid /api-gateway/api/v2/dtables/{base_uuid}/views/{view_name}/: get: tags: - Views summary: Get View operationId: getView description: Get the detailed settings of a view by its name. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/view_name_path" - $ref: "#/components/parameters/table_name" responses: "200": description: OK content: application/json: schema: type: object properties: _id: type: string name: type: string type: type: string is_locked: type: boolean filter_conjunction: type: string filters: type: array items: type: object sorts: type: array items: type: object groupbys: type: array items: type: object group_rows: type: array items: type: object groups: type: array items: type: object colorbys: type: object hidden_columns: type: array items: type: object rows: type: array items: type: object formula_rows: type: object link_rows: type: object summaries: type: object colors: type: object example: _id: r535 name: Default View type: table is_locked: false filter_conjunction: And filters: [] sorts: [] groupbys: [] group_rows: [] groups: [] colorbys: type: by_rules color_by_rules: - color: "#F4667C" filters: - column_key: "0000" filter_predicate: contains filter_term: "" filter_conjunction: Or hidden_columns: [] rows: [] formula_rows: {} link_rows: {} summaries: {} colors: {} put: tags: - Views summary: Update View operationId: updateView description: | Change the settings of a current view by its name. All parameters are optional. If you don't define a parameter, existing settings for this parameter will not be changed. To remove existing filters, sortings or groups you have to send an empty object like this: `"sorts": [{}]` requestBody: content: application/json: schema: $ref: "#/components/schemas/update_view" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/view_name_path" - $ref: "#/components/parameters/table_name" responses: "200": description: OK content: application/json: schema: type: object properties: _id: type: string name: type: string type: type: string is_locked: type: boolean filter_conjunction: type: string filters: type: array items: type: object sorts: type: array items: type: object groupbys: type: array items: type: object group_rows: type: array items: type: object groups: type: array items: type: object colorbys: type: object hidden_columns: type: array items: type: object rows: type: array items: type: object formula_rows: type: object link_rows: type: object summaries: type: object colors: type: object example: _id: r535 name: View1234567 type: table is_locked: false filter_conjunction: And filters: [] sorts: [] groupbys: [] group_rows: [] groups: [] colorbys: type: by_rules color_by_rules: - color: "#F4667C" filters: - column_key: "0000" filter_predicate: contains filter_term: "" filter_conjunction: Or hidden_columns: [] rows: [] formula_rows: {} link_rows: {} summaries: {} colors: {} "400": description: The target view name already exists in the table. content: application/json: example: error_msg: params invalid delete: tags: - Views summary: Delete View operationId: deleteView description: Delete a view by its name. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/view_name_path" - $ref: "#/components/parameters/table_name" responses: "200": description: OK content: application/json: schema: type: object example: success: true # Columns /api-gateway/api/v2/dtables/{base_uuid}/columns/: get: tags: - Columns summary: List Columns operationId: listColumns description: >- List all the visible columns in a certain view in a table. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/table_name" - $ref: "#/components/parameters/view_name" - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: columns: - key: "0000" name: Name type: text width: 200 editable: true resizable: true - key: g4s1 type: number name: api3 editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] post: tags: - Columns summary: Insert Column operationId: insertColumn description: >- Create a new column. You can only add one new column at the end of a table. requestBody: description: Choose which column type you want to add. If you want to add multiple columns, use the request [Append Columns](/reference/appendcolumns-1). content: application/json: schema: oneOf: - $ref: "#/components/schemas/text_column_with_table_name" - $ref: "#/components/schemas/long_text_column_with_table_name" - $ref: "#/components/schemas/number_column_with_table_name" - $ref: "#/components/schemas/collaborator_column_with_table_name" - $ref: "#/components/schemas/date_column_with_table_name" - $ref: "#/components/schemas/duration_column_with_table_name" - $ref: "#/components/schemas/single_select_column_with_table_name" - $ref: "#/components/schemas/multiple_select_column_with_table_name" - $ref: "#/components/schemas/image_column_with_table_name" - $ref: "#/components/schemas/file_column_with_table_name" - $ref: "#/components/schemas/email_column_with_table_name" - $ref: "#/components/schemas/url_column_with_table_name" - $ref: "#/components/schemas/checkbox_column_with_table_name" - $ref: "#/components/schemas/geolocation_column_with_table_name" - $ref: "#/components/schemas/rating_column_with_table_name" - $ref: "#/components/schemas/formula_column_with_table_name" - $ref: "#/components/schemas/link_column_with_table_name" - $ref: "#/components/schemas/link_formula_column_with_table_name" - $ref: "#/components/schemas/creator_column_with_table_name" - $ref: "#/components/schemas/ctime_column_with_table_name" - $ref: "#/components/schemas/last_modifier_column_with_table_name" - $ref: "#/components/schemas/mtime_column_with_table_name" - $ref: "#/components/schemas/autonumber_column_with_table_name" - $ref: "#/components/schemas/button_column_with_table_name" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object properties: key: type: string type: type: string name: type: string editable: type: boolean width: type: integer resizable: type: boolean draggable: type: boolean data: type: object nullable: true permission_type: type: string permitted_users: type: array items: type: string example: key: e48W type: link-formula name: How many links? editable: true width: 200 resizable: true draggable: true data: operated_columns: - Cw35 result_type: number formula: count_links link_column_key: Cw35 include_condition: false condition_conjunction: And conditions: [] permission_type: "" permitted_users: [] "400": description: A column with this name already exists in the table. content: application/json: example: Column ColA exists. put: tags: - Columns summary: Update Column operationId: updateColumn description: >- Allows various changes of the column: name, column_type, freeze/unfreeze, resize, etc... `op_type` is required. The following options are available: - rename_column - modify_column_type - resize_column - move_column - freeze_column `column` is the name or `key` of the target column. `new_column_type` is the new type of the target column. For a list of column type params refer to the SeaTable API Parameter. For further information on column types, check the page [Models](https://api.seatable.com/reference/models). requestBody: content: application/json: schema: $ref: "#/components/schemas/update_column" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object properties: key: type: string type: type: string name: type: string editable: type: boolean width: type: integer resizable: type: boolean draggable: type: boolean data: type: object nullable: true permission_type: type: string permitted_users: type: array items: type: string example: key: cSDV type: number name: New Oranges editable: true width: 400 resizable: true draggable: true data: null permission_type: "" permitted_users: [] "400": description: A column with this name already exists in the table. content: application/json: example: error_type: column_already_exists error_message: column name already exists delete: tags: - Columns summary: Delete Column operationId: deleteColumn description: |- Delete a column with its name or `key`. See the request body for detailed params. requestBody: content: application/json: schema: $ref: "#/components/schemas/delete_column" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/batch-append-columns/: post: tags: - Columns summary: Append Columns operationId: appendColumns description: >- Use this request to append multiple columns to your table at once. As for the request body, refer to the previous call, [Insert Column](/reference/insertcolumn-1), for a detailed list of column formats. These requested and optional params can be used in the request body: `table_name` is the name of your table, required. `columns` is a list of columns you'd like to append, in each object of which: * `column_name` is the name of your new column, required; * `column_type` is the type of your new column, required; * `column_data` is the format setting of a special column, required in case. For details, refer to the call [Insert Column](/reference/insertcolumn-1). Please note that you can't append `formula`, `link` or `link-formula` columns using this endpoint. Use the [Insert Column](https://api.seatable.com/reference/insertcolumn-1) endpoint instead. requestBody: content: application/json: schema: type: object properties: table_name: $ref: "#/components/schemas/table_name" columns: type: array items: oneOf: - $ref: "#/components/schemas/text_column" - $ref: "#/components/schemas/long_text_column" - $ref: "#/components/schemas/number_column" - $ref: "#/components/schemas/collaborator_column" - $ref: "#/components/schemas/date_column" - $ref: "#/components/schemas/duration_column" - $ref: "#/components/schemas/single_select_column" - $ref: "#/components/schemas/multiple_select_column" - $ref: "#/components/schemas/image_column" - $ref: "#/components/schemas/file_column" - $ref: "#/components/schemas/email_column" - $ref: "#/components/schemas/url_column" - $ref: "#/components/schemas/checkbox_column" - $ref: "#/components/schemas/rating_column" - $ref: "#/components/schemas/creator_column" - $ref: "#/components/schemas/ctime_column" - $ref: "#/components/schemas/last_modifier_column" - $ref: "#/components/schemas/mtime_column" - $ref: "#/components/schemas/autonumber_column" - $ref: "#/components/schemas/button_column" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: columns: - key: quLi type: text name: Name editable: true width: 200 resizable: true draggable: true data: null permission_type: "" permitted_users: [] description: null - key: X16v type: number name: Amount editable: true width: 200 resizable: true draggable: true data: format: number decimal: dot thousands: "no" permission_type: "" permitted_users: [] description: null /api-gateway/api/v2/dtables/{base_uuid}/column-options/: post: tags: - Columns summary: Add Single/Multiple Select Options operationId: addSelectOption description: >- Once you have created a single/multiple select column, use this request to add options for it. In the request body: `table_name` is the name of the table; `column` is the name or the `key` of the single/multiple select column; `options` is an array containing the label (`name`), option color (`color`) and the color of the arrow (`textColor`): ![Options](https://seatable.com/openapi/selectoptioncolor.png) requestBody: content: application/json: schema: $ref: "#/components/schemas/add_single__multiple_select_options" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true put: tags: - Columns summary: Update Single/Multiple Select Options operationId: updateSelectOption description: >- Use this request to update existing single/multiple select options by changing their name and/or color. In the request body: `table_name` is the name of your table, required; `column` is the name of the column, required; `options` is a list of option objects that you would like to update, in which: * `id` is the ID of that option, which you can retrive with the call "List Columns in A View in A Table", required; * `color` is the label's new color, optional; * `name` is the label's new name, optional. `return_options` gives you the possibility to get an overview of all the options you just updated, optional, `false` by default. requestBody: content: application/json: schema: $ref: "#/components/schemas/update_single__multiple_select_options" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: options: - name: Finished color: "#4ECCCB" textColor: "#FFFFFF" id: "119376" delete: tags: - Columns summary: Delete Single/Multiple Select Options operationId: deleteSelectOption description: >- Use this request to remove single select or multiple select options that you don't need any more. These deleted options will be removed from the entries containing them. In the request body: `table_name` is the name of the table; `column` is the name or the `key` of the single/multiple select column; `option_names` is a list of options you'd like to delete. requestBody: content: application/json: schema: $ref: "#/components/schemas/delete_select_options" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/column-cascade-settings/: post: tags: - Columns summary: Update Column Cascade Settings operationId: updateColumnCascade description: >- After you have added at least two single select columns and have added relevant options, you can start to set the cascade relationships between these single select columns. ## What are cascade settings? With cascade settings for the single select column, you can set up a "parent" single select column and a "child" single select column, so that when you select one option in the parent, the child column will only show you the options belonging to that parent. For example, if the parent column is "continent" and you've selected "Europe", then the child column will only show you the countries in Europe. Of course, this doesn't happen automatically - you have to set up the cascade relationship with this API request first. ![](https://seatable.com/openapi/cascade.png) ## What are the preconditions? This API request has the following preconditions: - The table already exists (This API request cannot create a new table); - The parent and child column already exist (same as above); - The parent and child column already have options (same as above). ## How to set up the cascade relationship? It's so easy: just like demonstrated in the example request, define the following parameters/objects and you'll get `success`: - `table_name`: The name of the table. - `parent_column`: The 1st level of single select column's name or `key`. - `child_column`: The 2nd level of single select column's name or `key`. - `cascade_settings`: In this object, list all the child options for each parent option, like demonstrated in the example request. requestBody: content: application/json: schema: type: object example: table_name: Table2 parent_column: Continent child_column: Country cascade_settings: Europe: - Germany - France Asia: - China - Japan security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true # Big Data /api-gateway/api/v2/dtables/{base_uuid}/add-archived-rows/: post: tags: [Big Data] summary: Add Rows into Big Data Backend operationId: addBigDataRows description: >- Insert rows directly into the big data backend. requestBody: content: application/json: schema: $ref: "#/components/schemas/insert_rows_into_big_data" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: inserted_row_count: 1 /api-gateway/api/v2/dtables/{base_uuid}/archive-view/: post: tags: [Big Data] summary: Move Rows to Big Data Backend operationId: moveRowsToBigData description: Select a view to move its rows to the big data backend. Note that the big data backend must be enabled in this base. security: - BaseTokenAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/archive-view" parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true error_message: "" /api-gateway/api/v2/dtables/{base_uuid}/unarchive/: post: tags: [Big Data] summary: Move Rows to Normal Backend operationId: moveRowsToNormalBackend description: Moves the selected rows from the big data backend to the normal backend. requestBody: content: application/json: schema: type: object properties: table_id: type: string description: The unique identifier of the table. example: "0000" row_ids: type: array items: type: string description: An array containing the row_ids of the rows you want to move from big data backend to normal. example: - "m-AlR40gSTGSxZvJN6ktaA" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true task_id: cdb7fcc6-d2fa-4bf7-ae08-0d767c38690c /api-gateway/api/v2/dtables/{base_uuid}/db-operations/: get: tags: [Big Data] summary: Get Base Big Data Operations operationId: getBaseBigDataOperations description: Get the operation logs of big data in a base. With the base's `base_uuid`. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: operations: - dtable_uuid: 91a377f36bce4e80a894b421b2801fce id: 77 op_time: 1721009252 op_type: update_links author: 12345678d1754bb4afa2c2cb7369d244@auth.local operation: >- {"count":2, "link_id":"3847", "table_id": "0000 ", "other_table_id ": "jCoR"} - dtable_uuid: 91a377f36bce4e80a894b421b2801fce id: 76 op_time: 1721009225 op_type: add_row author: 12345678d1754bb4afa2c2cb7369d244@auth.local operation: >- {"row_id":"171jHKAXRP69hD_NRApaRg", "table_id":"0000", "row_data":{"0000":"aaa", "_creator":"c6580a35560244bb9678c70bcdb55df5@auth.local", "_ctime": "2024-07-15T10:07:05.046579+08:00", "_id": "171jHKAXRP69hD_NRApaRg", "_last_modifier":"c6580a35560244bb9678c70bcdb55df5@auth.local","_mtime":"2024-07-15T10:07:05.046579+08:00"}} - dtable_uuid: 91a377f36bce4e80a894b421b2801fce id: 73 op_time: 1721009225 op_type: delete_links author: 12345678d1754bb4afa2c2cb7369d244@auth.local operation: >- {"count":2, "link_id":"3847", "table_id": "0000 ", "other_table_id ": "jCoR"} /api-gateway/api/v2/dtables/{base_uuid}/restore-operations/{op_id}/: put: tags: [Big Data] summary: Restore Big Data Operations operationId: restoreBigDataOperations description: Restore the operations by `op_id` of big data operation logs in a base. With the base's `base_uuid`. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/op_id_big_data_path" responses: "200": description: OK content: application/json: schema: type: object example: success:true # Row Comments /api-gateway/api/v2/dtables/{base_uuid}/comments/: get: tags: - Row Comments summary: List Row Comments operationId: listRowComments description: >- List all the comments in a certain row. The returned `id` value is the ID of each comment. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/row_id" responses: "200": description: OK content: application/json: schema: type: array items: type: object example: - id: 1 author: 28d006e7d1754bb4afa2c2cb7369d244@auth.local comment: This is good! dtable_uuid: 650d8a0d-7e27-46a8-8b18-6cc6374yf557 row_id: NAu2B3OcRG6UrWagL-9naA created_at: "2021-01-15T13:35:26.000Z" updated_at: "2021-01-15T13:35:26.000Z" resolved: 0 - id: 2 author: 28d006e7d1754bb4afa2c2cb7369d244@auth.local comment: Go online tomorrow? dtable_uuid: 650d8a0d-7e27-46a8-8b18-6cc6374yf557 row_id: NAu2B3OcRG6UrWagL-9naA created_at: "2021-01-15T13:52:48.000Z" updated_at: "2021-01-15T13:52:48.000Z" resolved: 0 - id: 3 author: 8cb2a6da1928374ba42905bf1647fd3f@auth.local comment: Agreed! dtable_uuid: 650d8a0d-7e27-46a8-8b18-6cc6374yf557 row_id: NAu2B3OcRG6UrWagL-9naA created_at: "2021-01-15T13:53:13.000Z" updated_at: "2021-01-15T13:53:13.000Z" resolved: 1 post: tags: - Row Comments summary: Create Row Comment operationId: createRowComment description: >- Create a comment for a certain row. security: - BaseTokenAuth: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/create_row_comment" parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/table_id" - $ref: "#/components/parameters/row_id" responses: "200": description: OK content: application/json: schema: type: object example: success:true /api-gateway/api/v2/dtables/{base_uuid}/comments/{comment_id}/: delete: tags: - Row Comments summary: Delete Comment operationId: deleteComment description: Delete a certain comment by its ID. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/comment_id" responses: "200": description: OK content: application/json: schema: type: object example: success: true get: tags: - Row Comments summary: Get Comment operationId: getComment description: Get the details of a certain comment with its ID. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/comment_id" responses: "200": description: OK content: application/json: schema: type: object properties: id: type: integer author: type: string comment: type: string dtable_uuid: type: string row_id: type: string created_at: type: string updated_at: type: string resolved: type: integer example: id: 1 author: 12345678d17570046f03c2cb7369d244@auth.local comment: Here is my email address dtable_uuid: 12345678-7e27-46a8-8b18-6cc6374yf557 row_id: NAu2B3OcRG6UrWagL-9naA created_at: "2021-01-15T13:52:48.000Z" updated_at: "2021-01-15T13:52:48.000Z" resolved: 0 /api-gateway/api/v2/dtables/{base_uuid}/comments-count/: get: tags: - Row Comments summary: Get Row Comments Count operationId: getRowCommentsCount description: >- Get the number of comments in a certain row. This could be a useful request to check if there's new comments there. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/row_id" responses: "200": description: OK content: application/json: schema: type: object example: count: 3 /api-gateway/api/v2/dtables/{base_uuid}/comments-within-days/: get: tags: - Row Comments summary: List Comments within Days operationId: listCommentsWithinDays description: >- List all the comments in a base within a given number of days before today. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/days" responses: "200": description: OK content: application/json: schema: type: object example: comments: - id: 1 author: 123456786569491ba42905bf1647fd3f@auth.local comment: Let's discuss this tomorrow dtable_uuid: 12345678-7e27-46a8-8b18-6cc6f3db2057 row_id: Qtf7xPmoRaiFyQPO1aNTjA created_at: "2021-03-09T15:54:22.000Z" updated_at: "2021-03-09T15:54:22.000Z" resolved: 0 /api/v2.1/dtables/{base_uuid}/rows-comments-num/: get: tags: - Row Comments summary: Get Number of Comments operationId: getNumberOfComments description: Get the number of comments for all rows. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: rows_comments_num: H44KC2bvThyMFD4ZtcD_-A: 2 C0LWRVCHT0OoAGjoXBuKMA: 1 # Notifications (Base) /api-gateway/api/v2/dtables/{base_uuid}/notifications/: get: tags: - Notifications summary: List Base Notifications operationId: listBaseNotifications description: List all the notifications, read or unread, in a base. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: notification_list: - id: 200 username: 123456786569491ba42905bf1647fd3f@auth.local msg_type: row_comment created_at: "2021-02-25T10:38:14.000Z" detail: author: 244b4667d1754bb4afa2c2cb7369d244@auth.local table_id: "0000" row_id: fS8qtN6FQ1uPOaNAC0Locw comment: Did you see this? seen: 1 put: tags: - Notifications summary: Mark Base Notifications as seen operationId: markBaseNotificationsAsSeen description: Use this request to mark all the notifications as read. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: seen: type: boolean description: true or false for read or unread. Otherwise invalid. example: true security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true delete: tags: - Notifications summary: Delete Base Notifications operationId: deleteBaseNotifications description: Delete all the notifications in the current base irrevocably. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/notifications/{notification_id}/: put: tags: - Notifications summary: Mark Notification Read/Unread operationId: markBaseNotificationAsSeen description: Mark a specific notification as read or unread. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: seen: type: boolean description: '`true` to mark as "seen" and `false` as "unseen".' example: false security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" - $ref: "#/components/parameters/notification_id" responses: "200": description: OK content: application/json: schema: type: object example: success: true /api-gateway/api/v2/dtables/{base_uuid}/ui-toasts/: post: tags: - Notifications summary: Send Toast Notification operationId: sendToastNotification description: Send a toast notification requestBody: content: application/json: schema: type: object properties: to_user: type: string description: "target username" example: "244b4667d1754bb4afa2c2cb7369d244@auth.local" toast_type: type: string description: "type of toast, e.g., success, warning, error" enum: ["success", "warning", "error"] example: "success" detail: type: object properties: msg: type: string description: "message will be toasted" example: "hello world!" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: success: true # Activities & Logs /api-gateway/api/v2/dtables/{base_uuid}/operations/: get: tags: - Activities & Logs summary: Get Base Activity Log operationId: getBaseActivityLog description: Get the activities log in a base. With the base's `base_uuid`. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: operations: - author: 12345678d1754bb4afa2c2cb7369d244@auth.local app: null op_time: 1610981745927 operation: >- {"op_type":"delete_column","table_id":"0000","column_key":"iJB4","old_column":{"rowType":"header","key":"iJB4","type":null,"name":null,"editable":true,"width":200,"resizable":true,"draggable":true,"data":null,"permission_type":"","permitted_users":[],"editor":{"key":null,"ref":null,"props":{},"_owner":null},"formatter":null,"left":1058,"idx":5},"upper_column_key":"LfGJ"} op_id: 118 - author: 12345678d1754bb4afa2c2cb7369d244@auth.local app: null op_time: 1610981742518 operation: >- {"op_type":"delete_column","table_id":"0000","column_key":"J2mq","old_column":{"rowType":"header","key":"J2mq","type":null,"name":null,"editable":true,"width":200,"resizable":true,"draggable":true,"data":null,"permission_type":"","permitted_users":[],"editor":{"key":null,"ref":null,"props":{},"_owner":null},"formatter":null,"left":280,"idx":2},"upper_column_key":"0000"} op_id: 117 - author: 12345678d1754bb4afa2c2cb7369d244@auth.local app: null op_time: 1610981739830 operation: >- {"op_type":"delete_column","table_id":"0000","column_key":"jQyv","old_column":{"rowType":"header","key":"jQyv","type":null,"name":null,"editable":true,"width":200,"resizable":true,"draggable":true,"data":null,"permission_type":"","permitted_users":[],"editor":{"key":null,"ref":null,"props":{},"_owner":null},"formatter":null,"left":480,"idx":3},"upper_column_key":"J2mq"} op_id: 116 /api-gateway/api/v2/dtables/{base_uuid}/activities/: get: tags: - Activities & Logs summary: List Row Activities operationId: listRowActivities description: List all the activities done to a certain row with the row's `row_id`. security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/row_id" - $ref: "#/components/parameters/page" - $ref: "#/components/parameters/per_page" - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: activities: - id: 6782 dtable_uuid: a57b56d3-1cc5-4ebd-8a6c-a1b28ac3dbdf row_id: YMIviMeERQCUiQhPPqo6Gw op_user: 0ef256cb715841dd81b147b2530c2904@auth.local op_type: modify_row op_time: "2021-01-14T09:01:57.000Z" detail: table_id: "0000" table_name: Table1 row_name: Meng row_data: - column_key: BydO column_name: Date column_type: date column_data: format: YYYY-MM-DD value: "2020-08-19" old_value: "2020-08-16" - id: 6778 dtable_uuid: a57b56d3-1cc5-4ebd-8a6c-a1b28ac3dbdf row_id: YMIviMeERQCUiQhPPqo6Gw op_user: 0ef256cb715841dd81b147b2530c2904@auth.local op_type: modify_row op_time: "2021-01-14T08:56:53.000Z" detail: table_id: "0000" table_name: Table1 row_name: Meng row_data: - column_key: "0000" column_name: Name column_type: text column_data: {} value: Meng old_value: "" - column_key: BydO column_name: Date column_type: date column_data: format: YYYY-MM-DD value: "2020-08-16" old_value: "" - id: 5960 dtable_uuid: a57b56d3-1cc5-4ebd-8a6c-a1b28ac3dbdf row_id: YMIviMeERQCUiQhPPqo6Gw op_user: 0ef256cb715841dd81b147b2530c2904@auth.local op_type: insert_row op_time: "2020-11-18T12:42:14.000Z" detail: table_id: "0000" table_name: Table1 row_name: "" row_data: - column_key: "0000" column_name: Name column_type: text column_data: {} value: "" total_count: 3 # Snapshots /api-gateway/api/v2/dtables/{base_uuid}/snapshot/: post: tags: [Snapshots] summary: Create Snapshot operationId: createSnapshot description: | Creates a snapshot for the current base. The pre-conditions are, that there's at least one change since the last snapshot and at least 10 minutes have passed. To get a list of already existing snapshots, use the the request [List Snapshots](/reference/listsnapshots). requestBody: content: application/json: schema: $ref: "#/components/schemas/generate_snapshot" security: - BaseTokenAuth: [] parameters: - $ref: "#/components/parameters/base_uuid" responses: "200": description: OK content: application/json: schema: type: object example: status: created snapshot: dtable_uuid: 650d8a0d-7e27-46a8-8b18-6cc6f3dbvh46 dtable_name: Example.dtable commit_id: 1234567813a3e0950d4d4f32bd744137929cef23 ctime: 1622111992159