openapi: 3.2.0
info:
  title: Budibase Views API
  description: The public API for Budibase apps and its services.
  version: 3.3.0
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).
security:
- ApiKeyAuth: []
tags:
- name: Views
paths:
  /views:
    post:
      operationId: viewCreate
      summary: Create a view
      description: Create a view, this can be against an internal or external table.
      tags:
      - Views
      parameters:
      - $ref: '#/components/parameters/appId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/view'
            examples:
              view:
                $ref: '#/components/examples/view'
      responses:
        '200':
          description: Returns the created view, including the ID which has been generated for it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewOutput'
              examples:
                view:
                  $ref: '#/components/examples/view'
  /views/{viewId}:
    put:
      operationId: viewUpdate
      summary: Update a view
      description: Update a view, this can be against an internal or external table.
      tags:
      - Views
      parameters:
      - $ref: '#/components/parameters/viewId'
      - $ref: '#/components/parameters/appId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/view'
            examples:
              view:
                $ref: '#/components/examples/view'
      responses:
        '200':
          description: Returns the updated view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewOutput'
              examples:
                view:
                  $ref: '#/components/examples/view'
    delete:
      operationId: viewDestroy
      summary: Delete a view
      description: Delete a view, this can be against an internal or external table.
      tags:
      - Views
      parameters:
      - $ref: '#/components/parameters/viewId'
      - $ref: '#/components/parameters/appId'
      responses:
        '200':
          description: Returns the deleted view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewOutput'
              examples:
                view:
                  $ref: '#/components/examples/view'
    get:
      operationId: viewGetById
      summary: Retrieve a view
      description: Lookup a view, this could be internal or external.
      tags:
      - Views
      parameters:
      - $ref: '#/components/parameters/viewId'
      - $ref: '#/components/parameters/appId'
      responses:
        '200':
          description: Returns the retrieved view.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewOutput'
              examples:
                view:
                  $ref: '#/components/examples/view'
  /views/search:
    post:
      operationId: viewSearch
      summary: Search for views
      description: Based on view properties (currently only name) search for views.
      tags:
      - Views
      parameters:
      - $ref: '#/components/parameters/appId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nameSearch'
      responses:
        '200':
          description: Returns the found views, based on the search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/viewSearch'
              examples:
                views:
                  $ref: '#/components/examples/views'
components:
  schemas:
    viewSearch:
      type: object
      properties:
        data:
          type: array
          items:
            description: The view to be created/updated.
            type: object
            required:
            - name
            - schema
            - tableId
            - id
            properties:
              name:
                description: The name of the view.
                type: string
              tableId:
                description: The ID of the table this view is based on.
                type: string
              type:
                description: The type of view - standard (empty value) or calculation.
                type: string
                enum:
                - calculation
              primaryDisplay:
                type: string
                description: A column used to display rows from this view - usually used when rendered in tables.
              query:
                description: Search parameters for view
                type: object
                properties:
                  logicalOperator:
                    description: When using groups this defines whether all of the filters must match, or only one of them.
                    type: string
                    enum:
                    - all
                    - any
                  onEmptyFilter:
                    description: If no filters match, should the view return all rows, or no rows.
                    type: string
                    enum:
                    - all
                    - none
                  groups:
                    description: A grouping of filters to be applied.
                    type: array
                    items:
                      type: object
                      properties:
                        logicalOperator:
                          description: When using groups this defines whether all of the filters must match, or only one of them.
                          type: string
                          enum:
                          - all
                          - any
                        filters:
                          description: A list of filters to apply
                          type: array
                          items:
                            type: object
                            properties:
                              operator:
                                type: string
                                description: The type of search operation which is being performed.
                                enum:
                                - equal
                                - notEqual
                                - empty
                                - notEmpty
                                - fuzzy
                                - string
                                - contains
                                - notContains
                                - containsAny
                                - oneOf
                                - notOneOf
                                - range
                              field:
                                type: string
                                description: The field in the view to perform the search on.
                              value:
                                description: The value to search for - the type will depend on the operator in use.
                                oneOf:
                                - type: string
                                - type: number
                                - type: boolean
                                - type: object
                                - type: array
                        groups:
                          description: A grouping of filters to be applied.
                          type: array
                          items:
                            type: object
                            properties:
                              logicalOperator:
                                description: When using groups this defines whether all of the filters must match, or only one of them.
                                type: string
                                enum:
                                - all
                                - any
                              filters:
                                description: A list of filters to apply
                                type: array
                                items:
                                  type: object
                                  properties:
                                    operator:
                                      type: string
                                      description: The type of search operation which is being performed.
                                      enum:
                                      - equal
                                      - notEqual
                                      - empty
                                      - notEmpty
                                      - fuzzy
                                      - string
                                      - contains
                                      - notContains
                                      - containsAny
                                      - oneOf
                                      - notOneOf
                                      - range
                                    field:
                                      type: string
                                      description: The field in the view to perform the search on.
                                    value:
                                      description: The value to search for - the type will depend on the operator in use.
                                      oneOf:
                                      - type: string
                                      - type: number
                                      - type: boolean
                                      - type: object
                                      - type: array
              sort:
                oneOf:
                - type: object
                  required:
                  - field
                  properties:
                    field:
                      type: string
                      description: The field from the table/view schema to sort on.
                    order:
                      type: string
                      description: The order in which to sort.
                      enum:
                      - ascending
                      - descending
                    type:
                      type: string
                      description: The type of sort to perform (by number, or by alphabetically).
                      enum:
                      - string
                      - number
                - type: array
                  items:
                    type: object
                    required:
                    - field
                    properties:
                      field:
                        type: string
                        description: The field from the table/view schema to sort on.
                      order:
                        type: string
                        description: The order in which to sort.
                        enum:
                        - ascending
                        - descending
                      type:
                        type: string
                        description: The type of sort to perform (by number, or by alphabetically).
                        enum:
                        - string
                        - number
              schema:
                type: object
                additionalProperties:
                  oneOf:
                  - type: object
                    properties:
                      visible:
                        type: boolean
                        description: Defines whether the column is visible or not - rows retrieved/updated through this view will not be able to access it.
                      readonly:
                        type: boolean
                        description: 'When used in combination with ''visible: true'' the column will be visible in row responses but cannot be updated.'
                      order:
                        type: integer
                        description: A number defining where the column shows up in tables, lowest being first.
                      width:
                        type: integer
                        description: A width for the column, defined in pixels - this affects rendering in tables.
                      column:
                        type: array
                        description: If this is a relationship column, we can set the columns we wish to include
                        items:
                          type: object
                          properties:
                            readonly:
                              type: boolean
                  - type: object
                    properties:
                      calculationType:
                        type: string
                        description: This column should be built from a calculation, specifying a type and field. It is important to note when a calculation is configured all non-calculation columns will be used for grouping.
                        enum:
                        - sum
                        - avg
                        - count
                        - min
                        - max
                      field:
                        type: string
                        description: The field from the table to perform the calculation on.
                      distinct:
                        type: boolean
                        description: Can be used in tandem with the count calculation type, to count unique entries.
              id:
                description: The ID of the view.
                type: string
      required:
      - data
    nameSearch:
      type: object
      properties:
        name:
          type: string
          description: The name to be used when searching - this will be used in a case insensitive starts with match.
      required:
      - name
    view:
      description: The view to be created/updated.
      type: object
      required:
      - name
      - schema
      - tableId
      properties:
        name:
          description: The name of the view.
          type: string
        tableId:
          description: The ID of the table this view is based on.
          type: string
        type:
          description: The type of view - standard (empty value) or calculation.
          type: string
          enum:
          - calculation
        primaryDisplay:
          type: string
          description: A column used to display rows from this view - usually used when rendered in tables.
        query:
          description: Search parameters for view
          type: object
          properties:
            logicalOperator:
              description: When using groups this defines whether all of the filters must match, or only one of them.
              type: string
              enum:
              - all
              - any
            onEmptyFilter:
              description: If no filters match, should the view return all rows, or no rows.
              type: string
              enum:
              - all
              - none
            groups:
              description: A grouping of filters to be applied.
              type: array
              items:
                type: object
                properties:
                  logicalOperator:
                    description: When using groups this defines whether all of the filters must match, or only one of them.
                    type: string
                    enum:
                    - all
                    - any
                  filters:
                    description: A list of filters to apply
                    type: array
                    items:
                      type: object
                      properties:
                        operator:
                          type: string
                          description: The type of search operation which is being performed.
                          enum:
                          - equal
                          - notEqual
                          - empty
                          - notEmpty
                          - fuzzy
                          - string
                          - contains
                          - notContains
                          - containsAny
                          - oneOf
                          - notOneOf
                          - range
                        field:
                          type: string
                          description: The field in the view to perform the search on.
                        value:
                          description: The value to search for - the type will depend on the operator in use.
                          oneOf:
                          - type: string
                          - type: number
                          - type: boolean
                          - type: object
                          - type: array
                  groups:
                    description: A grouping of filters to be applied.
                    type: array
                    items:
                      type: object
                      properties:
                        logicalOperator:
                          description: When using groups this defines whether all of the filters must match, or only one of them.
                          type: string
                          enum:
                          - all
                          - any
                        filters:
                          description: A list of filters to apply
                          type: array
                          items:
                            type: object
                            properties:
                              operator:
                                type: string
                                description: The type of search operation which is being performed.
                                enum:
                                - equal
                                - notEqual
                                - empty
                                - notEmpty
                                - fuzzy
                                - string
                                - contains
                                - notContains
                                - containsAny
                                - oneOf
                                - notOneOf
                                - range
                              field:
                                type: string
                                description: The field in the view to perform the search on.
                              value:
                                description: The value to search for - the type will depend on the operator in use.
                                oneOf:
                                - type: string
                                - type: number
                                - type: boolean
                                - type: object
                                - type: array
        sort:
          oneOf:
          - type: object
            required:
            - field
            properties:
              field:
                type: string
                description: The field from the table/view schema to sort on.
              order:
                type: string
                description: The order in which to sort.
                enum:
                - ascending
                - descending
              type:
                type: string
                description: The type of sort to perform (by number, or by alphabetically).
                enum:
                - string
                - number
          - type: array
            items:
              type: object
              required:
              - field
              properties:
                field:
                  type: string
                  description: The field from the table/view schema to sort on.
                order:
                  type: string
                  description: The order in which to sort.
                  enum:
                  - ascending
                  - descending
                type:
                  type: string
                  description: The type of sort to perform (by number, or by alphabetically).
                  enum:
                  - string
                  - number
        schema:
          type: object
          additionalProperties:
            oneOf:
            - type: object
              properties:
                visible:
                  type: boolean
                  description: Defines whether the column is visible or not - rows retrieved/updated through this view will not be able to access it.
                readonly:
                  type: boolean
                  description: 'When used in combination with ''visible: true'' the column will be visible in row responses but cannot be updated.'
                order:
                  type: integer
                  description: A number defining where the column shows up in tables, lowest being first.
                width:
                  type: integer
                  description: A width for the column, defined in pixels - this affects rendering in tables.
                column:
                  type: array
                  description: If this is a relationship column, we can set the columns we wish to include
                  items:
                    type: object
                    properties:
                      readonly:
                        type: boolean
            - type: object
              properties:
                calculationType:
                  type: string
                  description: This column should be built from a calculation, specifying a type and field. It is important to note when a calculation is configured all non-calculation columns will be used for grouping.
                  enum:
                  - sum
                  - avg
                  - count
                  - min
                  - max
                field:
                  type: string
                  description: The field from the table to perform the calculation on.
                distinct:
                  type: boolean
                  description: Can be used in tandem with the count calculation type, to count unique entries.
    viewOutput:
      type: object
      properties:
        data:
          description: The view to be created/updated.
          type: object
          required:
          - name
          - schema
          - tableId
          - id
          properties:
            name:
              description: The name of the view.
              type: string
            tableId:
              description: The ID of the table this view is based on.
              type: string
            type:
              description: The type of view - standard (empty value) or calculation.
              type: string
              enum:
              - calculation
            primaryDisplay:
              type: string
              description: A column used to display rows from this view - usually used when rendered in tables.
            query:
              description: Search parameters for view
              type: object
              properties:
                logicalOperator:
                  description: When using groups this defines whether all of the filters must match, or only one of them.
                  type: string
                  enum:
                  - all
                  - any
                onEmptyFilter:
                  description: If no filters match, should the view return all rows, or no rows.
                  type: string
                  enum:
                  - all
                  - none
                groups:
                  description: A grouping of filters to be applied.
                  type: array
                  items:
                    type: object
                    properties:
                      logicalOperator:
                        description: When using groups this defines whether all of the filters must match, or only one of them.
                        type: string
                        enum:
                        - all
                        - any
                      filters:
                        description: A list of filters to apply
                        type: array
                        items:
                          type: object
                          properties:
                            operator:
                              type: string
                              description: The type of search operation which is being performed.
                              enum:
                              - equal
                              - notEqual
                              - empty
                              - notEmpty
                              - fuzzy
                              - string
                              - contains
                              - notContains
                              - containsAny
                              - oneOf
                              - notOneOf
                              - range
                            field:
                              type: string
                              description: The field in the view to perform the search on.
                            value:
                              description: The value to search for - the type will depend on the operator in use.
                              oneOf:
                              - type: string
                              - type: number
                              - type: boolean
                              - type: object
                              - type: array
                      groups:
                        description: A grouping of filters to be applied.
                        type: array
                        items:
                          type: object
                          properties:
                            logicalOperator:
                              description: When using groups this defines whether all of the filters must match, or only one of them.
                              type: string
                              enum:
                              - all
                              - any
                            filters:
                              description: A list of filters to apply
                              type: array
                              items:
                                type: object
                                properties:
                                  operator:
                                    type: string
                                    description: The type of search operation which is being performed.
                                    enum:
                                    - equal
                                    - notEqual
                                    - empty
                                    - notEmpty
                                    - fuzzy
                                    - string
                                    - contains
                                    - notContains
                                    - containsAny
                                    - oneOf
                                    - notOneOf
                                    - range
                                  field:
                                    type: string
                                    description: The field in the view to perform the search on.
                                  value:
                                    description: The value to search for - the type will depend on the operator in use.
                                    oneOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                                    - type: object
                                    - type: array
            sort:
              oneOf:
              - type: object
                required:
                - field
                properties:
                  field:
                    type: string
                    description: The field from the table/view schema to sort on.
                  order:
                    type: string
                    description: The order in which to sort.
                    enum:
                    - ascending
                    - descending
                  type:
                    type: string
                    description: The type of sort to perform (by number, or by alphabetically).
                    enum:
                    - string
                    - number
              - type: array
                items:
                  type: object
                  required:
                  - field
                  properties:
                    field:
                      type: string
                      description: The field from the table/view schema to sort on.
                    order:
                      type: string
                      description: The order in which to sort.
                      enum:
                      - ascending
                      - descending
                    type:
                      type: string
                      description: The type of sort to perform (by number, or by alphabetically).
                      enum:
                      - string
                      - number
            schema:
              type: object
              additionalProperties:
                oneOf:
                - type: object
                  properties:
                    visible:
                      type: boolean
                      description: Defines whether the column is visible or not - rows retrieved/updated through this view will not be able to access it.
                    readonly:
                      type: boolean
                      description: 'When used in combination with ''visible: true'' the column will be visible in row responses but cannot be updated.'
                    order:
                      type: integer
                      description: A number defining where the column shows up in tables, lowest being first.
                    width:
                      type: integer
                      description: A width for the column, defined in pixels - this affects rendering in tables.
                    column:
                      type: array
                      description: If this is a relationship column, we can set the columns we wish to include
                      items:
                        type: object
                        properties:
                          readonly:
                            type: boolean
                - type: object
                  properties:
                    calculationType:
                      type: string
                      description: This column should be built from a calculation, specifying a type and field. It is important to note when a calculation is configured all non-calculation columns will be used for grouping.
                      enum:
                      - sum
                      - avg
                      - count
                      - min
                      - max
                    field:
                      type: string
                      description: The field from the table to perform the calculation on.
                    distinct:
                      type: boolean
                      description: Can be used in tandem with the count calculation type, to count unique entries.
            id:
              description: The ID of the view.
              type: string
      required:
      - data
  parameters:
    viewId:
      in: path
      name: viewId
      required: true
      description: The ID of the view 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
  examples:
    view:
      value:
        data:
          name: peopleView
          tableId: ta_896a325f7e8147d2a2cda93c5d236511
          schema:
            name:
              visible: true
              readonly: false
              order: 1
              width: 300
            age:
              visible: true
              readonly: true
              order: 2
              width: 200
            salary:
              visible: false
              readonly: false
          query:
            logicalOperator: all
            onEmptyFilter: none
            groups:
            - logicalOperator: any
              filters:
              - operator: string
                field: name
                value: John
              - operator: range
                field: age
                value:
                  low: 18
                  high: 100
          primaryDisplay: name
    views:
      value:
        data:
        - name: peopleView
          tableId: ta_896a325f7e8147d2a2cda93c5d236511
          schema:
            name:
              visible: true
              readonly: false
              order: 1
              width: 300
            age:
              visible: true
              readonly: true
              order: 2
              width: 200
            salary:
              visible: false
              readonly: false
          query:
            logicalOperator: all
            onEmptyFilter: none
            groups:
            - logicalOperator: any
              filters:
              - operator: string
                field: name
                value: John
              - operator: range
                field: age
                value:
                  low: 18
                  high: 100
          primaryDisplay: name
  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.