budibase/packages/server/specs/openapi.yaml

openapi: 3.0.0
info:
  title: Budibase API
  description: The public API for Budibase apps and its services.
  version: 1.0.0
servers:
  - url: http://budibase.app/api/public/v1
    description: Budibase Cloud API
  - url: "{protocol}://{hostname}:10000/api/public/v1"
    description: Budibase self hosted API
components:
  parameters:
    tableId:
      in: path
      name: tableId
      required: true
      description: The ID of the table which this request is targeting.
      schema:
        type: string
    rowId:
      in: path
      name: rowId
      required: true
      description: The ID of the row which this request is targeting.
      schema:
        type: string
    appId:
      in: header
      name: appId
      required: true
      description: The ID of the app which this request is targeting.
      schema:
        type: string
  examples:
    table:
      value:
        _id: ta_5b1649e42a5b41dea4ef7742a36a7a70
        name: People
        schema:
          name:
            type: string
            name: name
          age:
            type: number
            name: age
          relationship:
            type: link
            name: relationship
            tableId: ta_...
            fieldName: relatedColumn
            relationshipType: many-to-many
    tables:
      value:
        - _id: ta_5b1649e42a5b41dea4ef7742a36a7a70
          name: People
          schema:
            name:
              type: string
              name: name
            age:
              type: number
              name: age
            relationship:
              type: link
              name: relationship
              tableId: ta_...
              fieldName: relatedColumn
              relationshipType: many-to-many
    inputRow:
      value:
        _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
        type: row
        tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
        name: Mike
        age: 30
        relationship:
          - ro_ta_...
    row:
      value:
        _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
        type: row
        tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
        name: Mike
        age: 30
        relationship:
          - primaryDisplay: Joe
            _id: ro_ta_...
    search:
      value:
        rows:
          - _id: ro_ta_5b1649e42a5b41dea4ef7742a36a7a70_e6dc7e38cf1343b2b56760265201cda4
            type: row
            tableId: ta_5b1649e42a5b41dea4ef7742a36a7a70
            name: Mike
            age: 30
            relationship:
              - primaryDisplay: Joe
                _id: ro_ta_...
        hasNextPage: true
        bookmark: 10
  securitySchemes:
    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.
  schemas:
    row:
      description: The row to be created/updated, based on the table schema.
      type: object
      additionalProperties:
        oneOf:
          - type: string
          - type: object
          - type: integer
          - type: array
          - type: boolean
security:
  - ApiKeyAuth: []
paths:
  "/tables/{tableId}/rows/search":
    post:
      summary: Used to search for rows within a table.
      tags:
        - rows
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: object
                  properties:
                    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: A fuzzy search, only supported by internal tables.
                    range:
                      type: object
                      description: Searches within a range, the format of this must be columnName ->
                        [low, high].
                      example:
                        columnName1:
                          - 10
                          - 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].
                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.
      responses:
        "200":
          description: The response will contain an array of rows that match the search
            parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    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:
                    oneOf:
                      - type: string
                      - type: integer
                    description: If pagination in use, this should be provided.
                  hasNextPage:
                    description: If pagination in use, this will determine if there is another page
                      to fetch.
                    type: boolean
              examples:
                search:
                  $ref: "#/components/examples/search"
  "/tables/{tableId}/rows":
    post:
      summary: Creates a new row within a 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:
                type: object
              examples:
                row:
                  $ref: "#/components/examples/row"
  "/tables/{tableId}/rows/{rowId}":
    put:
      summary: Update a single row within a 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:
                type: object
              examples:
                row:
                  $ref: "#/components/examples/row"
    delete:
      summary: Delete a single row from 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:
                type: object
              examples:
                row:
                  $ref: "#/components/examples/row"
    get:
      summary: Get a single row from the specified table.
      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:
                type: object
              examples:
                row:
                  $ref: "#/components/examples/row"
  /tables/search:
    post:
      summary: Search internal and external tables based on their name.
      parameters:
        - $ref: "#/components/parameters/appId"
      tags:
        - tables
      requestBody: null
      responses:
        "200":
          description: Returns the found tables, based on the search parameters.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
              examples:
                tables:
                  $ref: "#/components/examples/tables"
  /tables:
    post:
      summary: Create a new table.
      parameters:
        - $ref: "#/components/parameters/appId"
      tags:
        - tables
      responses:
        "200":
          description: Returns the created table, including the ID which has been
            generated for it. This can be internal or external data sources.
          content:
            application/json:
              schema:
                type: object
              examples:
                table:
                  $ref: "#/components/examples/table"
    get:
      summary: Get all the tables, internal and external within an app.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      responses:
        "200":
          description: Returns all of the tables which were found.
          content:
            application/json:
              schema:
                type: object
              examples:
                table:
                  $ref: "#/components/examples/row"
  /tables/:tableId:
    put:
      summary: Update the specified table. This can be for internal or external tables.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      responses:
        "200":
          description: Returns the updated table.
          content:
            application/json:
              schema:
                type: object
              examples:
                table:
                  $ref: "#/components/examples/row"
  "/tables/{tableId}":
    delete:
      summary: Delete a single table and all of its data.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      responses:
        "200":
          description: Returns the deleted table.
          content:
            application/json:
              schema:
                type: object
              examples:
                table:
                  $ref: "#/components/examples/table"
tags: []