openapi: 3.0.3
info:
title: Baserow API spec Admin Database table rows API
version: 2.2.2
description: 'For more information about our REST API, please visit [this page](https://baserow.io/docs/apis%2Frest-api).
For more information about our deprecation policy, please visit [this page](https://baserow.io/docs/apis%2Fdeprecations).'
contact:
url: https://baserow.io/contact
license:
name: MIT
url: https://github.com/baserow/baserow/blob/develop/LICENSE
tags:
- name: Database table rows
paths:
/api/database/rows/names/:
get:
operationId: list_database_table_row_names
description: Returns the names of the given row of the given tables. The nameof a row is the primary field value for this row. The result can be usedfor example, when you want to display the name of a linked row from another table.
parameters:
- in: query
name: table__{id}
schema:
type: string
description: A list of comma separated row ids to query from the table with id {id}. For example, if you want the name of row `42` and `43` from table `28` this parameter will be `table__28=42,43`. You can specify multiple rows for different tables but every tables must be in the same database. You need at least read permission on all specified tables.
tags:
- Database table rows
security:
- UserSource JWT: []
- JWT: []
- Database token: []
responses:
'200':
content:
application/json:
schema:
type: object
properties:
'{table_id}*':
type: object
description: An object containing the row names of table `table_id`.
properties:
'{row_id}*':
type: string
description: the name of the row with id `row_id` from table with id `table_id`.
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_USER_NOT_IN_GROUP
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'401':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_NO_PERMISSION_TO_TABLE
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_TABLE_DOES_NOT_EXIST
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
/api/database/rows/table/{table_id}/:
get:
operationId: list_database_table_rows
description: Lists all the rows of the table related to the provided parameter if the user has access to the related database's workspace. The response is paginated by a page/size style. It is also possible to provide an optional search query, only rows where the data matches the search query are going to be returned then. The properties of the returned rows depends on which fields the table has. For a complete overview of fields use the **list_database_table_fields** endpoint to list them all. In the example all field types are listed, but normally the number in field_{id} key is going to be the id of the field. Or if the GET parameter `user_field_names` is provided then the keys will be the name of the field. The value is what the user has provided and the format of it depends on the fields type.
parameters:
- in: query
name: exclude
schema:
type: string
description: 'All the fields are included in the response by default. You can select a subset of fields by providing the exclude query parameter. If you for example provide the following GET parameter `exclude=field_1,field_2` then the fields with id `1` and id `2` are going to be excluded from the selection and response. If the `user_field_names` parameter is provided then instead exclude should be a comma separated list of the actual field names. For field names with commas you should surround the name with quotes like so: `exclude=My Field,"Field With , "`. A backslash can be used to escape field names which contain double quotes like so: `exclude=My Field,Field with \"`.'
- in: query
name: filter__{field}__{filter}
schema:
type: string
description: "The rows can optionally be filtered by the same view filters available for the views. Multiple filters can be provided if they follow the same format. The field and filter variable indicate how to filter and the value indicates where to filter on.\n\nFor example if you provide the following GET parameter `filter__field_1__equal=test` then only rows where the value of field_1 is equal to test are going to be returned.\n\nThe following filters are available: equal, not_equal, filename_contains, files_lower_than, has_file_type, contains, contains_not, contains_word, doesnt_contain_word, length_is_lower_than, higher_than, higher_than_or_equal, lower_than, lower_than_or_equal, is_even_and_whole, date_equal, date_before, date_before_or_equal, date_after_days_ago, date_after, date_after_or_equal, date_not_equal, date_equals_today, date_before_today, date_after_today, date_within_days, date_within_weeks, date_within_months, date_equals_days_ago, date_equals_months_ago, date_equals_years_ago, date_equals_week, date_equals_month, date_equals_day_of_month, date_equals_year, date_is, date_is_not, date_is_before, date_is_on_or_before, date_is_after, date_is_on_or_after, date_is_within, single_select_equal, single_select_not_equal, single_select_is_any_of, single_select_is_none_of, link_row_has, link_row_has_not, link_row_contains, link_row_not_contains, boolean, empty, not_empty, multiple_select_has, multiple_select_has_not, multiple_collaborators_has, multiple_collaborators_has_not, user_is, user_is_not, has_value_equal, has_not_value_equal, has_value_contains, has_not_value_contains, has_value_contains_word, has_not_value_contains_word, has_value_length_is_lower_than, has_all_values_equal, has_empty_value, has_not_empty_value, has_any_select_option_equal, has_none_select_option_equal, has_value_lower, has_value_lower_or_equal, has_value_higher, has_value_higher_or_equal, has_not_value_higher_or_equal, has_not_value_higher, has_not_value_lower_or_equal, has_not_value_lower, has_date_equal, has_not_date_equal, has_date_before, has_not_date_before, has_date_on_or_before, has_not_date_on_or_before, has_date_on_or_after, has_not_date_on_or_after, has_date_after, has_not_date_after, has_date_within, has_not_date_within.\n\n**Please note that if the `filters` parameter is provided, this parameter will be ignored.** \n\n"
- in: query
name: filter_type
schema:
type: string
description: '`AND`: Indicates that the rows must match all the provided filters.
`OR`: Indicates that the rows only have to match one of the filters.
This works only if two or more filters are provided.
**Please note that if the `filters` parameter is provided, this parameter will be ignored.**'
- in: query
name: filters
schema:
type: string
description: "A JSON serialized string containing the filter tree to apply to this view. The filter tree is a nested structure containing the filters that need to be applied. \n\nAn example of a valid filter tree is the following:`{\"filter_type\": \"AND\", \"filters\": [{\"field\": 1, \"type\": \"equal\", \"value\": \"test\"}]}`. The `field` value must be the ID of the field to filter on, or the name of the field if `user_field_names` is true.\n\nThe following filters are available: equal, not_equal, filename_contains, files_lower_than, has_file_type, contains, contains_not, contains_word, doesnt_contain_word, length_is_lower_than, higher_than, higher_than_or_equal, lower_than, lower_than_or_equal, is_even_and_whole, date_equal, date_before, date_before_or_equal, date_after_days_ago, date_after, date_after_or_equal, date_not_equal, date_equals_today, date_before_today, date_after_today, date_within_days, date_within_weeks, date_within_months, date_equals_days_ago, date_equals_months_ago, date_equals_years_ago, date_equals_week, date_equals_month, date_equals_day_of_month, date_equals_year, date_is, date_is_not, date_is_before, date_is_on_or_before, date_is_after, date_is_on_or_after, date_is_within, single_select_equal, single_select_not_equal, single_select_is_any_of, single_select_is_none_of, link_row_has, link_row_has_not, link_row_contains, link_row_not_contains, boolean, empty, not_empty, multiple_select_has, multiple_select_has_not, multiple_collaborators_has, multiple_collaborators_has_not, user_is, user_is_not, has_value_equal, has_not_value_equal, has_value_contains, has_not_value_contains, has_value_contains_word, has_not_value_contains_word, has_value_length_is_lower_than, has_all_values_equal, has_empty_value, has_not_empty_value, has_any_select_option_equal, has_none_select_option_equal, has_value_lower, has_value_lower_or_equal, has_value_higher, has_value_higher_or_equal, has_not_value_higher_or_equal, has_not_value_higher, has_not_value_lower_or_equal, has_not_value_lower, has_date_equal, has_not_date_equal, has_date_before, has_not_date_before, has_date_on_or_before, has_not_date_on_or_before, has_date_on_or_after, has_not_date_on_or_after, has_date_after, has_not_date_after, has_date_within, has_not_date_within.\n\n**Please note that if this parameter is provided, all other `filter__{field}__{filter}` will be ignored, as well as the `filter_type` parameter.**"
- in: query
name: include
schema:
type: string
description: 'All the fields are included in the response by default. You can select a subset of fields by providing the include query parameter. If you for example provide the following GET parameter `include=field_1,field_2` then only the fields withid `1` and id `2` are going to be selected and included in the response. If the `user_field_names` parameter is provided then instead include should be a comma separated list of the actual field names. For field names with commas you should surround the name with quotes like so: `include=My Field,"Field With , "`. A backslash can be used to escape field names which contain double quotes like so: `include=My Field,Field with \"`.'
- in: query
name: order_by
schema:
type: string
description: 'Optionally the rows can be ordered by provided field ids separated by comma. By default a field is ordered in ascending (A-Z) order, but by prepending the field with a ''-'' it can be ordered descending (Z-A). If the `user_field_names` parameter is provided then instead order_by should be a comma separated list of the actual field names. For field names with commas you should surround the name with quotes like so: `order_by=My Field,"Field With , "`. A backslash can be used to escape field names which contain double quotes like so: `order_by=My Field,Field with \"`.'
- in: query
name: page
schema:
type: integer
description: Defines which page of rows should be returned.
- in: query
name: search
schema:
type: string
description: If provided only rows with data that matches the search query are going to be returned.
- in: query
name: search_mode
schema:
type: string
description: If provided, allows API consumers to determine what kind of search experience they wish to have. If the default `SearchMode.FT_WITH_COUNT` is used, then Postgres full-text search is used. If `SearchMode.COMPAT` is provided then the search term will be exactly searched for including whitespace on each cell. This is the Baserow legacy search behaviour.
- in: query
name: size
schema:
type: integer
description: Defines how many rows should be returned per page.
- in: path
name: table_id
schema:
type: integer
description: Returns the rows of the table related to the provided value.
required: true
- in: query
name: user_field_names
schema:
type: boolean
description: 'A flag query parameter that, if provided with one of the following values: `y`, `yes`, `true`, `t`, `on`, `1`, or an empty value, will cause the returned JSON to use the user-specified field names instead of the internal Baserow field names (e.g., field_123).'
- in: query
name: view_id
schema:
type: integer
description: Includes all the filters and sorts of the provided view.
- in: query
name: '{link_row_field}__join={target_field},{target_field2}'
schema:
type: string
description: This parameter allows you to request a lookup of field values from a target table through existing link row fields. The parameter name has to be the name of an existing link row field, followed by `__join`. The value should be a list of field names for which we want to lookup additional values. You can provide one or multiple target fields. It is not possible to lookup a value of a link row field in the target table. If `user_field_names` parameter is set, the names of the fields should be user field names. In this case the resulting field names in the output will also be user field names. The used link row field has to be among the requested fields if using the `include` or `exclude` parameters.
tags:
- Database table rows
security:
- UserSource JWT: []
- JWT: []
- Database token: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginationSerializerExampleRowResponseSerializerWithUserFieldNames'
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_USER_NOT_IN_GROUP
- ERROR_REQUEST_BODY_VALIDATION
- ERROR_PAGE_SIZE_LIMIT
- ERROR_ORDER_BY_FIELD_NOT_FOUND
- ERROR_ORDER_BY_FIELD_NOT_POSSIBLE
- ERROR_FILTER_FIELD_NOT_FOUND
- ERROR_VIEW_FILTER_TYPE_DOES_NOT_EXIST
- ERROR_VIEW_FILTER_TYPE_UNSUPPORTED_FIELD
- ERROR_FILTERS_PARAM_VALIDATION_ERROR
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'401':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_NO_PERMISSION_TO_TABLE
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_TABLE_DOES_NOT_EXIST
- ERROR_FIELD_DOES_NOT_EXIST
- ERROR_VIEW_DOES_NOT_EXIST
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
post:
operationId: create_database_table_row
description: Creates a new row in the table if the user has access to the related table's workspace. The accepted body fields are depending on the fields that the table has. For a complete overview of fields use the **list_database_table_fields** to list them all. None of the fields are required, if they are not provided the value is going to be `null` or `false` or some default value is that is set. If you want to add a value for the field with for example id `10`, the key must be named `field_10`. Or instead if the `user_field_names` GET param is provided the key must be the name of the field. Of course multiple fields can be provided in one request. In the examples below you will find all the different field types, the numbers/ids in the example are just there for example purposes, the field_ID must be replaced with the actual id of the field or the name of the field if `user_field_names` is provided.
parameters:
- in: header
name: ClientSessionId
schema:
type: string
format: uuid
description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
- in: header
name: ClientUndoRedoActionGroupId
schema:
type: string
format: uuid
description: An optional header that marks the action performed by this request as having occurred in a particular action group.Then calling the undo/redo endpoint with the same ClientSessionId header, all the actions belonging to the same action group can be undone/redone together in a single API call.
- in: query
name: before
schema:
type: integer
description: If provided then the newly created row will be positioned before the row with the provided id.
- in: query
name: send_webhook_events
schema:
type: boolean
description: A flag query parameter that triggers webhooks after the operation, if set to `y`, `yes`, `true`, `t`, `on`, `1`, or left empty. Defaults to `true`
- in: path
name: table_id
schema:
type: integer
description: Creates a row in the table related to the provided value.
required: true
- in: query
name: user_field_names
schema:
type: boolean
description: 'A flag query parameter that, if provided with one of the following values: `y`, `yes`, `true`, `t`, `on`, `1`, or an empty value, will cause this endpoint to expect and return the user-specified field names instead of the internal Baserow field names (e.g., field_123).'
- in: query
name: view
schema:
type: integer
description: Provide if the row is created in a view. This can result in different permission checking and default values.
tags:
- Database table rows
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ExampleRowRequestSerializerWithUserFieldNames'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ExampleRowRequestSerializerWithUserFieldNames'
multipart/form-data:
schema:
$ref: '#/components/schemas/ExampleRowRequestSerializerWithUserFieldNames'
security:
- UserSource JWT: []
- JWT: []
- Database token: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ExampleRowResponseSerializerWithUserFieldNames'
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_USER_NOT_IN_GROUP
- ERROR_REQUEST_BODY_VALIDATION
- ERROR_REQUEST_BODY_VALIDATION
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'401':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_NO_PERMISSION_TO_TABLE
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_TABLE_DOES_NOT_EXIST
- ERROR_ROW_DOES_NOT_EXIST
- ERROR_VIEW_DOES_NOT_EXIST
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
/api/database/rows/table/{table_id}/{row_id}/:
get:
operationId: get_database_table_row
description: Fetches an existing row from the table if the user has access to the related table's workspace. The properties of the returned row depend on which fields the table has. For a complete overview of fields use the **list_database_table_fields** endpoint to list them all. In the example all field types are listed, but normally the number in field_{id} key is going to be the id of the field of the field. Or if the GET parameter `user_field_names` is provided then the keys will be the name of the field. The value is what the user has provided and the format of it depends on the fields type.
parameters:
- in: query
name: include
schema:
type: string
description: Optionally include row's `metadata` in the response. The `metadata` object includes extra row specific data like the 'row_comments_notification_mode' settings, if available.
- in: path
name: row_id
schema:
type: integer
description: Returns the row related the provided value.
required: true
- in: path
name: table_id
schema:
type: integer
description: Returns the row of the table related to the provided value.
required: true
- in: query
name: user_field_names
schema:
type: boolean
description: 'A flag query parameter that, if provided with one of the following values: `y`, `yes`, `true`, `t`, `on`, `1`, or an empty value, will cause the returned JSON to use the user-specified field names instead of the internal Baserow field names (e.g., field_123).'
- in: query
name: view
schema:
type: integer
description: Provide if the row if fetched in a view. This can result in different permission checking and default values.
tags:
- Database table rows
security:
- UserSource JWT: []
- JWT: []
- Database token: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ExampleRowResponseSerializerWithUserFieldNames'
description: ''
'400':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_USER_NOT_IN_GROUP
- ERROR_REQUEST_BODY_VALIDATION
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'401':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_NO_PERMISSION_TO_TABLE
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
'404':
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Machine readable error indicating what went wrong.
enum:
- ERROR_TABLE_DOES_NOT_EXIST
- ERROR_ROW_DOES_NOT_EXIST
- ERROR_VIEW_DOES_NOT_EXIST
detail:
oneOf:
- type: string
format: string
description: Human readable details about what went wrong.
- type: object
format: object
description: Machine readable object about what went wrong.
description: ''
patch:
operationId: update_database_table_row
description: Updates an existing row in the table if the user has access to the related table's workspace. The accepted body fields are depending on the fields that the table has. For a complete overview of fields use the **list_database_table_fields** endpoint to list them all. None of the fields are required, if they are not provided the value is not going to be updated. When you want to update a value for the field with id `10`, the key must be named `field_10`. Or if the GET parameter `user_field_names` is provided the key of the field to update must be the name of the field. Multiple different fields to update can be provided in one request. In the examples below you will find all the different field types, the numbers/ids in the example are just there for example purposes, the field_ID must be replaced with the actual id of the field or the name of the field if `user_field_names` is provided.
parameters:
- in: header
name: ClientSessionId
schema:
type: string
format: uuid
description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
- in: header
name: ClientUndoRedoActionGroupId
schema:
type: string
format: uuid
description: An optional header that marks the action performed by this request as having occurred in a particular action group.Then calling the undo/redo endpoint with the same ClientSessionId header, all the actions belonging to the same action group can be undone/redone together in a single API call.
- in: path
name: row_id
schema:
type: integer
description: Updates the row related to the value.
required: true
- in: query
name: send_webhook_events
schema:
type: boolean
description: A flag query parameter that triggers webhooks after the operation, if set to `y`, `yes`, `true`, `t`, `on`, `1`, or left empty. Defaults to `true`
- in: path
name: table_id
schema:
type: integer
description: Updates the row in the table related to the value.
required: true
- in: query
name: user_field_names
schema:
type: boolean
description: 'A flag query parameter that, if provided with one of the following values: `y`, `yes`, `true`, `t`, `on`, `1`, or an empty value, will cause this endpoint to expect and return the user-specified field names instead of the internal Baserow field names (e.g., field_123).'
- in: query
name: view
schema:
type: integer
description: Provide if the row is updated in a view. This can result in different permission checking and default values.
tags:
- Database table rows
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedExampleUpdateRowRequestSerializerWithUserFieldNames'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedExampleUpdateRowRequestSerializerWithUserFieldNames'
multipart/form-data:
schema:
# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/baserow/refs/heads/main/openapi/baserow-database-table-rows-api-openapi.yml