Baserow Builder data sources API

openapi: 3.0.3
info:
  title: Baserow API spec Admin Builder data sources 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: Builder data sources
paths:
  /api/builder/data-source/{data_source_id}/:
    patch:
      operationId: update_builder_page_data_source
      description: Updates an existing builder data_source.
      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: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedIntegration_ServiceUpdateDataSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedIntegration_ServiceUpdateDataSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedIntegration_ServiceUpdateDataSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration_ServiceDataSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - 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: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_SOURCE_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: ''
    delete:
      operationId: delete_builder_page_data_source
      description: Deletes the data_source related by the given id.
      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: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source
        required: true
      tags:
      - Builder data sources
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - 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: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_SOURCE_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/builder/data-source/{data_source_id}/dispatch/:
    post:
      operationId: dispatch_builder_page_data_source
      description: Dispatches the service of the related data_source and returns the result.
      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: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source you want to call the dispatch for
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_SOURCE_DOES_NOT_EXIST
                    - ERROR_ELEMENT_DOES_NOT_EXIST
                    - ERROR_DATA_SOURCE_REFINEMENT_FORBIDDEN
                    - ERROR_SERVICE_IMPROPERLY_CONFIGURED
                    - ERROR_SERVICE_INVALID_DISPATCH_CONTEXT
                    - ERROR_SERVICE_INVALID_DISPATCH_CONTEXT_CONTENT
                    - ERROR_SERVICE_UNEXPECTED_DISPATCH_ERROR
                    - ERROR_SERVICE_SORT_PROPERTY_DOES_NOT_EXIST
                    - ERROR_SERVICE_FILTER_PROPERTY_DOES_NOT_EXIST
                    - ERROR_DATA_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/builder/data-source/{data_source_id}/move/:
    patch:
      operationId: move_builder_page_data_source
      description: Moves the data_source in the page before another data_source or at the end of the page if no before data_source is given. The data_sources must belong to the same page.
      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: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source to move
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedMoveDataSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedMoveDataSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedMoveDataSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration_ServiceDataSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_REQUEST_BODY_VALIDATION
                    - ERROR_DATA_SOURCE_NOT_IN_SAME_PAGE
                  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_DATA_SOURCE_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/builder/data-source/{data_source_id}/record-names/:
    get:
      operationId: get_record_names_builder_page_data_source
      description: Find the record names associated with a given list of record ids.
      parameters:
      - in: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source to find the record names.
        required: true
      - in: query
        name: record_ids
        schema:
          type: string
        description: A comma separated list of the record ids to search for.
        explode: false
      tags:
      - Builder data sources
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  description: Record name
                description: A dictionary mapping record ids to their names.
                example:
                  '1': Record name 1
                  '2': Record name 2
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_SERVICE_IMPROPERLY_CONFIGURED
                  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_DATA_SOURCE_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/builder/domains/published/data-source/{data_source_id}/dispatch/:
    post:
      operationId: dispatch_public_builder_page_data_source
      description: Dispatches the service of the related data_source and returns the result.
      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: path
        name: data_source_id
        schema:
          type: integer
        description: The id of the data_source you want to call the dispatch for
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_SOURCE_DOES_NOT_EXIST
                    - ERROR_ELEMENT_DOES_NOT_EXIST
                    - ERROR_DATA_SOURCE_REFINEMENT_FORBIDDEN
                    - ERROR_SERVICE_IMPROPERLY_CONFIGURED
                    - ERROR_SERVICE_INVALID_DISPATCH_CONTEXT
                    - ERROR_SERVICE_INVALID_DISPATCH_CONTEXT_CONTENT
                    - ERROR_SERVICE_UNEXPECTED_DISPATCH_ERROR
                    - ERROR_SERVICE_SORT_PROPERTY_DOES_NOT_EXIST
                    - ERROR_SERVICE_FILTER_PROPERTY_DOES_NOT_EXIST
                    - ERROR_DATA_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/builder/domains/published/page/{page_id}/data_sources/:
    get:
      operationId: list_public_builder_page_data_sources
      description: Lists all the data_sources of the page related to the provided parameter if the builder is public.
      parameters:
      - in: path
        name: page_id
        schema:
          type: integer
        description: Returns only the data_sources of the page related to the provided Id if the related builder is public.
        required: true
      tags:
      - Builder data sources
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration_ServicePublicDataSource'
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_PAGE_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/builder/domains/published/page/{page_id}/dispatch-data-sources/:
    post:
      operationId: dispatch_public_builder_page_data_sources
      description: Dispatches the service of the related page data_sources
      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: path
        name: page_id
        schema:
          type: integer
        description: The page we want to dispatch the data source for.
        required: true
      tags:
      - Builder data sources
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_DOES_NOT_EXIST
                    - ERROR_PAGE_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/builder/page/{page_id}/data-sources/:
    get:
      operationId: list_builder_page_data_sources
      description: Lists all the data_sources of the page related to the provided parameter if the user has access to the related builder's workspace. If the workspace is related to a template, then this endpoint will be publicly accessible.
      parameters:
      - in: path
        name: page_id
        schema:
          type: integer
        description: Returns only the data_sources of the page related to the provided Id.
        required: true
      tags:
      - Builder data sources
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration_ServiceDataSource'
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_PAGE_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_builder_page_data_source
      description: Creates a new builder data_source
      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: path
        name: page_id
        schema:
          type: integer
        description: Creates a data_source for the builder page related to the provided value.
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Integration_ServiceCreateDataSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Integration_ServiceCreateDataSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Integration_ServiceCreateDataSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration_ServiceDataSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - 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: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_PAGE_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/builder/page/{page_id}/dispatch-data-sources/:
    post:
      operationId: dispatch_builder_page_data_sources
      description: Dispatches the service of the related page data_sources
      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: path
        name: page_id
        schema:
          type: integer
        description: The page we want to dispatch the data source for.
        required: true
      tags:
      - Builder data sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DispatchDataSourceRequest'
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_DATA_DOES_NOT_EXIST
                    - ERROR_PAGE_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: ''
components:
  schemas:
    LocalBaserowListRowsDataSource:
      type: object
      description: 'A serializer mixin for services which implement the local Baserow filterable mixin.

        It ensures that when serialize the service, *all* filters (including those pointing

        to trashed fields) are serialized.'
      properties:
        id:
          type: integer
          readOnly: true
          description: Data source id.
        integration_id:
          type: integer
          nullable: true
          description: The id of the Baserow integration we want the data for.
        type:
          type: string
          readOnly: true
          description: The type of the data source.
        schema:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The schema of the service.
        context_data:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The context data of the service.
        context_data_schema:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The schema context data of the service.
        sample_data:
          readOnly: true
          nullable: true
          description: Store the sample data used for generating a schema.
        name:
          type: string
          readOnly: true
          description: Human name for this data source.
        page_id:
          type: integer
          readOnly: true
          description: Page this data source is linked to.
        order:
          type: number
          format: float
          readOnly: true
          description: Lowest first.
        table_id:
          type: integer
          nullable: true
          description: The id of the Baserow table we want the data for.
        view_id:
          type: integer
          nullable: true
          description: The id of the Baserow view we want the data for.
        filter_type:
          allOf:
          - $ref: '#/components/schemas/ConditionTypeEnum'
          description: 'Indicates whether all the rows should apply to all filters (AND) or to any filter (OR).


            * `AND` - And

            * `OR` - Or'
        search_query:
          type: object
          additionalProperties: {}
          default:
            formula: ''
            version: '0.1'
            mode: simple
          description: Any search queries to apply to the service when it is dispatched.
        default_result_count:
          type: integer
          maximum: 2147483647
          minimum: 0
          description: The default record count returned with each page.
      required:
      - context_data
      - context_data_schema
      - id
      - name
      - order
      - page_id
      - sample_data
      - schema
      - type
    NullEnum:
      enum:
      - null
    LocalBaserowUpsertRowDataSource:
      type: object
      description: 'Basic data_source serializer mostly for returned values. This serializer flatten the

        service properties so that from an API POV the data_source object only exists.'
      properties:
        id:
          type: integer
          readOnly: true
          description: Data source id.
        integration_id:
          type: integer
          nullable: true
          description: The id of the Baserow integration we want the data for.
        type:
          type: string
          readOnly: true
          description: The type of the data source.
        schema:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The schema of the service.
        context_data:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The context data of the service.
        context_data_schema:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The schema context data of the service.
        sample_data:
          readOnly: true
          nullable: true
          description: Store the sample data used for generating a schema.
        name:
          type: string
          readOnly: true
          description: Human name for this data source.
        page_id:
          type: integer
          readOnly: true
          description: Page this data source is linked to.
        order:
          type: number
          format: float
          readOnly: true
          description: Lowest first.
        table_id:
          type: integer
          nullable: true
          description: The id of the Baserow table we want the data for.
        field_mappings:
          type: array
          items:
            $ref: '#/components/schemas/LocalBaserowTableServiceFieldMapping'
          description: The field mapping associated with this service.
        row_id:
          type: object
          additionalProperties: {}
          default:
            formula: ''
            version: '0.1'
            mode: simple
          description: A formula for defining the intended row.
      required:
      - context_data
      - context_data_schema
      - id
      - name
      - order
      - page_id
      - sample_data
      - schema
      - type
    LocalBaserowDeleteRowUpdateDataSource:
      type: object
      properties:
        integration_id:
          type: integer
          nullable: true
          description: The id of the Baserow integration we want the data for.
        name:
          type: string
        table_id:
          type: integer
          nullable: true
          description: The id of the Baserow table we want the data for.
        row_id:
          type: object
          additionalProperties: {}
          default:
            formula: ''
            version: '0.1'
            mode: simple
          description: A formula for defining the intended row.
    CorePeriodicServiceUpdateDataSource:
      type: object
      properties:
        in

# --- truncated at 32 KB (257 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/baserow/refs/heads/main/openapi/baserow-builder-data-sources-api-openapi.yml