Baserow Builder data sources API

openapi: 3.2.0
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
servers:
- url: https://api.baserow.io
  description: Base URL declared by the provider in apis.yml (roadmap#122).
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:
    LocalBaserowTableServiceAggregationGroupBy:
      type: object
      properties:
        order:
          type: integer
          readOnly: true
        field_id:
          type:
          - integer
          - 'null'
      required:
      - field_id
      - order
    AiOutputType5efEnum:
      enum:
      - text
      - choice
      type: string
      description: '* `text` - Text

        * `choice` - Choice'
    LocalBaserowRowsCreatedCreateDataSource:
      type: object
      description: 'This serializer allow to set the type of a data_source and the data_source id

        before which we want to insert the new data_source.'
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/Type634Enum'
          description: 'The type of the service.


            * `local_baserow_get_row` - local_baserow_get_row

            * `local_baserow_list_rows` - local_baserow_list_rows

            * `local_baserow_aggregate_rows` - local_baserow_aggregate_rows

            * `local_baserow_upsert_row` - local_baserow_upsert_row

            * `local_baserow_delete_row` - local_baserow_delete_row

            * `local_baserow_rows_created` - local_baserow_rows_created

            * `local_baserow_rows_updated` - local_baserow_rows_updated

            * `local_baserow_rows_deleted` - local_baserow_rows_deleted

            * `slack_write_message` - slack_write_message

            * `http_request` - http_request

            * `smtp_email` - smtp_email

            * `router` - router

            * `http_trigger` - http_trigger

            * `iterator` - iterator

            * `periodic` - periodic

            * `ai_agent` - ai_agent

            * `local_baserow_grouped_aggregate_rows` - local_baserow_grouped_aggregate_rows'
        name:
          type:
          - string
          - 'null'
          description: Human name for this data source.
        page_id:
          type:
          - integer
          - 'null'
          description: Page this data source is linked to.
        before_id:
          type: integer
          description: If provided, creates the data_source before the data_source with the given id.
        table_id:
          type:
          - integer
          - 'null'
          description: The id of the Baserow table we want the data for.
        integration_id:
          type:
          - integer
          - 'null'
          description: The id of the Baserow integration we want the data for.
    CoreHTTPRequestServicePublicDataSource:
      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.
        type:
          type: string
          readOnly: true
          description: The type of the data source.
        schema:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The schema of the service.
        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.
        context_data:
          type: object
          additionalProperties: {}
          readOnly: true
          description: The context data of the data source.
        http_method:
          allOf:
          - $ref: '#/components/schemas/HttpMethodEnum'
          default: GET
          description: 'The HTTP method to use for the request (e.g., GET, POST).


            * `GET` - GET

            * `POST` - POST

            * `PUT` - PUT

            * `DELETE` - DELETE

            * `PATCH` - PATCH

            * `HEAD` - HEAD

            * `OPTIONS` - OPTIONS'
        url:
          type: object
          additionalProperties: {}
          default:
            formula: ''
            version: '0.1'
            mode: simple
          description: The URL to which the HTTP request will be sent.
        headers:
          type: array
          items:
            $ref: '#/components/schemas/HTTPHeader'
          description: The headers for the request.
        query_params:
          type: array
          items:
            $ref: '#/components/schemas/HTTPQueryParam'
          description: The query params for the request.
        form_data:
          type: array
          items:
            $ref: '#/components/schemas/HTTPFormData'
          description: The form data for the request.
        body_type:
          allOf:
          - $ref: '#/components/schemas/BodyType870Enum'
          default: none
          description: 'The type of the body content (e.g., JSON, Form Data).


            * `json` - JSON

            * `form` - Form Data

            * `raw` - Raw

            * `none` - None'
        body_content:
          type: object
          additionalProperties: {}
          default:
            formula: ''
            version: '0.1'
            mode: simple
          description: The content of the body of the HTTP request.
        timeout:
          type: integer
          maximum: 120
          minimum: 1
          description: The timeout for the HTTP request in seconds.
        sample_data:
          description: Store the sample data used for generating a schema.
      required:
      - context_data
      - id
      - name
      - order
      - page_id
      - schema
      - type
    LocalBaserowDeleteRowDataSource:
      type: object
      description: 'Basic data_source serializer mostly for returned value

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