Budibase Rows API

openapi: 3.2.0
info:
  title: Budibase Rows API
  version: '1.0'
  description: 'Operations tagged Rows across 2 of this provider''s published API definitions: budibase-openapi.yml, budibase-rows-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://budibase.app/api/public/v1
  description: Budibase Cloud Public API
- url: https://{selfhosted}/api/public/v1
  description: Self-hosted Budibase
  variables:
    selfhosted:
      default: budibase.example.com
      description: Hostname of the self-hosted Budibase instance
tags:
- name: Rows
  description: Manage rows inside a table.
paths:
  /tables/{id}/rows:
    parameters:
    - $ref: '#/components/parameters/IdPath'
    get:
      tags:
      - Rows
      summary: Search for rows in a table
      operationId: searchRows
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RowSearch'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Row'
      security:
      - apiKeyAuth: []
    post:
      tags:
      - Rows
      summary: Create a row
      operationId: createRow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Row'
      responses:
        '200':
          description: Created row
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
      security:
      - apiKeyAuth: []
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud Public API
    - url: https://{selfhosted}/api/public/v1
      description: Self-hosted Budibase
      variables:
        selfhosted:
          default: budibase.example.com
          description: Hostname of the self-hosted Budibase instance
  /tables/{id}/rows/{rowId}:
    parameters:
    - $ref: '#/components/parameters/IdPath'
    - name: rowId
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Rows
      summary: Retrieve a row
      operationId: getRow
      responses:
        '200':
          description: Row
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
      security:
      - apiKeyAuth: []
    put:
      tags:
      - Rows
      summary: Update a row
      operationId: updateRow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Row'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Row'
      security:
      - apiKeyAuth: []
    delete:
      tags:
      - Rows
      summary: Delete a row
      operationId: deleteRow
      responses:
        '200':
          description: Deleted
      security:
      - apiKeyAuth: []
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud Public API
    - url: https://{selfhosted}/api/public/v1
      description: Self-hosted Budibase
      variables:
        selfhosted:
          default: budibase.example.com
          description: Hostname of the self-hosted Budibase instance
  /tables/{tableId}/rows:
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud API
      variables:
        apiKey:
          default: <user API key>
          description: The API key of the user to assume for API call.
        appId:
          default: <App ID>
          description: The ID of the app the calls will be executed within the context of, this should start with app_ (production) or app_dev (development).
    post:
      operationId: rowCreate
      summary: Create a row
      description: Creates a row within the specified table.
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/tableId'
      - $ref: '#/components/parameters/appId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/row'
            examples:
              row:
                $ref: '#/components/examples/inputRow'
      responses:
        '200':
          description: Returns the created row, including the ID which has been generated for it. This can be found in the Budibase portal, viewed under the developer information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rowOutput'
              examples:
                row:
                  $ref: '#/components/examples/row'
      security:
      - ApiKeyAuth: []
  /tables/{tableId}/rows/{rowId}:
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud API
      variables:
        apiKey:
          default: <user API key>
          description: The API key of the user to assume for API call.
        appId:
          default: <App ID>
          description: The ID of the app the calls will be executed within the context of, this should start with app_ (production) or app_dev (development).
    put:
      operationId: rowUpdate
      summary: Update a row
      description: Updates a row within the specified table.
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/tableId'
      - $ref: '#/components/parameters/rowId'
      - $ref: '#/components/parameters/appId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/row'
            examples:
              row:
                $ref: '#/components/examples/inputRow'
      responses:
        '200':
          description: Returns the created row, including the ID which has been generated for it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rowOutput'
              examples:
                row:
                  $ref: '#/components/examples/row'
      security:
      - ApiKeyAuth: []
    delete:
      operationId: rowDestroy
      summary: Delete a row
      description: Deletes a row within the specified table.
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/tableId'
      - $ref: '#/components/parameters/rowId'
      - $ref: '#/components/parameters/appId'
      responses:
        '200':
          description: Returns the deleted row, including the ID which has been generated for it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rowOutput'
              examples:
                row:
                  $ref: '#/components/examples/row'
      security:
      - ApiKeyAuth: []
    get:
      operationId: rowGetById
      summary: Retrieve a row
      description: This gets a single row, it will be enriched with the full related rows, rather than the squashed "primaryDisplay" format returned by the search endpoint.
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/tableId'
      - $ref: '#/components/parameters/rowId'
      - $ref: '#/components/parameters/appId'
      responses:
        '200':
          description: Returns the retrieved row.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rowOutput'
              examples:
                enrichedRow:
                  $ref: '#/components/examples/enrichedRow'
      security:
      - ApiKeyAuth: []
  /tables/{tableId}/rows/search:
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud API
      variables:
        apiKey:
          default: <user API key>
          description: The API key of the user to assume for API call.
        appId:
          default: <App ID>
          description: The ID of the app the calls will be executed within the context of, this should start with app_ (production) or app_dev (development).
    post:
      operationId: rowSearch
      summary: Search for rows
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/tableId'
      - $ref: '#/components/parameters/appId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rowSearch'
      responses:
        '200':
          description: The response will contain an array of rows that match the search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchOutput'
              examples:
                search:
                  $ref: '#/components/examples/rows'
      security:
      - ApiKeyAuth: []
  /views/{viewId}/rows/search:
    servers:
    - url: https://budibase.app/api/public/v1
      description: Budibase Cloud API
      variables:
        apiKey:
          default: <user API key>
          description: The API key of the user to assume for API call.
        appId:
          default: <App ID>
          description: The ID of the app the calls will be executed within the context of, this should start with app_ (production) or app_dev (development).
    post:
      operationId: rowViewSearch
      summary: Search for rows in a view
      tags:
      - Rows
      parameters:
      - $ref: '#/components/parameters/viewId'
      - $ref: '#/components/parameters/appId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/rowSearch'
      responses:
        '200':
          description: The response will contain an array of rows that match the search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchOutput'
              examples:
                search:
                  $ref: '#/components/examples/rows'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    Row:
      type: object
      properties:
        _id:
          type: string
        _rev:
          type: string
        tableId:
          type: string
      additionalProperties: true
    RowSearch:
      type: object
      properties:
        query:
          type: object
          additionalProperties: true
        paginate:
          type: boolean
        bookmark:
          type: string
        limit:
          type: integer
        sort:
          type: object
          properties:
            order:
              type: string
              enum:
              - ascending
              - descending
            column:
              type: string
            type:
              type: string
    rowSearch:
      type: object
      properties:
        query:
          type: object
          properties:
            allOr:
              type: boolean
              description: Specifies that a row should be returned if it satisfies any of the specified options, rather than requiring it to fulfill all the search parameters. This defaults to false, meaning AND logic will be used.
            string:
              type: object
              example:
                columnName1: value
                columnName2: value
              description: A map of field name to the string to search for, this will look for rows that have a value starting with the string value.
              additionalProperties:
                type: string
                description: The value to search for in the column.
            fuzzy:
              type: object
              description: Searches for a sub-string within a string column, e.g. searching for 'dib' will match 'Budibase'.
            range:
              type: object
              description: Searches within a range, the format of this must be in the format of an object with a "low" and "high" property.
              example:
                columnName1:
                  low: 10
                  high: 20
            equal:
              type: object
              description: Searches for rows that have a column value that is exactly the value set.
            notEqual:
              type: object
              description: Searches for any row which does not contain the specified column value.
            empty:
              type: object
              description: Searches for rows which do not contain the specified column. The object should simply contain keys of the column names, these can map to any value.
              example:
                columnName1: ''
            notEmpty:
              type: object
              description: Searches for rows which have the specified column.
            oneOf:
              type: object
              description: Searches for rows which have a column value that is any of the specified values. The format of this must be columnName -> [value1, value2].
            contains:
              type: object
              description: Searches for a value, or set of values in array column types (such as a multi-select). If an array of search options is provided then it must match all.
              example:
                arrayColumn:
                - a
                - b
            notContains:
              type: object
              description: The logical inverse of contains. Only works on array column types. If an array of values is passed, the row must not match any of them to be returned in the response.
              example:
                arrayColumn:
                - a
                - b
            containsAny:
              type: object
              description: As with the contains search, only works on array column types and searches for any of the provided values when given an array.
              example:
                arrayColumn:
                - a
                - b
        paginate:
          type: boolean
          description: Enables pagination, by default this is disabled.
        bookmark:
          oneOf:
          - type: string
          - type: integer
          description: If retrieving another page, the bookmark from the previous request must be supplied.
        limit:
          type: integer
          description: The maximum number of rows to return, useful when paginating, for internal tables this will be limited to 1000, for SQL tables it will be 5000.
        sort:
          type: object
          description: A set of parameters describing the sort behaviour of the search.
          properties:
            order:
              type: string
              enum:
              - ascending
              - descending
              description: The order of the sort, by default this is ascending.
            column:
              type: string
              description: The name of the column by which the rows will be sorted.
            type:
              type: string
              enum:
              - string
              - number
              description: Defines whether the column should be treated as a string or as numbers when sorting.
      required:
      - query
    row:
      description: The row to be created/updated, based on the table schema.
      type: object
      additionalProperties:
        description: Key value properties of any type, depending on the table schema.
    searchOutput:
      type: object
      required:
      - data
      properties:
        data:
          description: An array of rows, these will each contain an _id field which can be used to update or delete them.
          type: array
          items:
            type: object
        bookmark:
          description: If pagination in use, this should be provided.
          oneOf:
          - type: string
          - type: integer
        hasNextPage:
          description: If pagination in use, this will determine if there is another page to fetch.
          type: boolean
    rowOutput:
      type: object
      properties:
        data:
          description: The row to be created/updated, based on the table schema.
          type: object
          additionalProperties:
            description: Key value properties of any type, depending on the table schema.
          properties:
            _id:
              description: The ID of the row.
              type: string
            tableId:
              description: The ID of the table this row comes from.
              type: string
          required:
          - tableId
          - _id
      required:
      - data
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
    rowId:
      in: path
      name: rowId
      required: true
      description: The ID of the row which this request is targeting.
      schema:
        type: string
    tableId:
      in: path
      name: tableId
      required: true
      description: The ID of the table which this request is targeting.
      schema:
        type: string
    appId:
      in: header
      name: x-budibase-app-id
      required: true
      description: The ID of the app which this request is targeting.
      schema:
        default: '{{appId}}'
        type: string
    viewId:
      in: path
      name: viewId
      required: true
      description: The ID of the view which this request is targeting.
      schema:
        type: string
  examples:
    rows:
      value:
        data:
        - _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
          type: row
          tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
          name: Mike
          age: 30
          relationship:
          - primaryDisplay: Joe
            _id: ro_ta_...
        hasNextPage: true
        bookmark: 10
    enrichedRow:
      value:
        data:
          _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
          name: eg
          tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
          type: row
          relationship:
          - _id: ro_ta_users_us_8f3d717147d74d759d8cef5b6712062f
            name: Joe
            tableId: ta_users
            internal:
            - _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
              primaryDisplay: eg
    inputRow:
      value:
        _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
        type: row
        tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
        name: Mike
        age: 30
        relationship:
        - ro_ta_...
    row:
      value:
        data:
          _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
          type: row
          tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
          name: Mike
          age: 30
          relationship:
          - primaryDisplay: Joe
            _id: ro_ta_...
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-budibase-api-key
      description: API key generated from the Budibase portal user dropdown menu.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-budibase-api-key
      description: Your individual API key, this will provide access based on the configured RBAC settings of your user.
x-refined-from:
- budibase-openapi.yml
- budibase-rows-api-openapi.yml