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: x-budibase-app-id
      required: true
      description: The ID of the app which this request is targeting.
      schema:
        type: string
    appIdUrl:
      in: path
      name: appId
      required: true
      description: The ID of the app which this request is targeting.
      schema:
        type: string
    queryId:
      in: path
      name: queryId
      required: true
      description: The ID of the query which this request is targeting.
      schema:
        type: string
    userId:
      in: path
      name: userId
      required: true
      description: The ID of the user which this request is targeting.
      schema:
        type: string
  examples:
    application:
      value:
        data:
          _id: app_metadata
          appId: app_dev_957b12f943d348faa61db7e18e088d0f
          version: 1.0.58-alpha.0
          name: App name
          url: /app-url
          tenantId: default
          updatedAt: 2022-02-22T13:00:54.035Z
          createdAt: 2022-02-11T18:02:26.961Z
          status: development
    applications:
      value:
        data:
          - _id: app_metadata
            appId: app_dev_957b12f943d348faa61db7e18e088d0f
            version: 1.0.58-alpha.0
            name: App name
            url: /app-url
            tenantId: default
            updatedAt: 2022-02-22T13:00:54.035Z
            createdAt: 2022-02-11T18:02:26.961Z
            status: development
    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_...
    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
    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
    table:
      value:
        data:
          _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:
        data:
          - _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
    query:
      value:
        data:
          _id: query_datasource_plus_4d8be0c506b9465daf4bf84d890fdab6_454854487c574d45bc4029b1e153219e
          datasourceId: datasource_plus_4d8be0c506b9465daf4bf84d890fdab6
          parameters: []
          fields:
            sql: select * from persons
          queryVerb: read
          name: Help
          schema:
            personid:
              name: personid
              type: string
            lastname:
              name: lastname
              type: string
            firstname:
              name: firstname
              type: string
            address:
              name: address
              type: string
            city:
              name: city
              type: string
          transformer: return data
          readable: true
    queries:
      value:
        data:
          - _id: query_datasource_plus_4d8be0c506b9465daf4bf84d890fdab6_454854487c574d45bc4029b1e153219e
            datasourceId: datasource_plus_4d8be0c506b9465daf4bf84d890fdab6
            parameters: []
            fields:
              sql: select * from persons
            queryVerb: read
            name: Help
            schema:
              personid:
                name: personid
                type: string
              lastname:
                name: lastname
                type: string
              firstname:
                name: firstname
                type: string
              address:
                name: address
                type: string
              city:
                name: city
                type: string
            transformer: return data
            readable: true
    restResponse:
      value:
        data:
          - value: <html lang='en-GB'></html>
        pagination:
          cursor: "2"
        raw: <html lang='en-GB'></html>
        headers:
          content-type: text/html; charset=ISO-8859-1
    sqlResponse:
      value:
        data:
          - personid: 1
            lastname: Hughes
            firstname: Mike
            address: 123 Fake Street
            city: Belfast
          - personid: 2
            lastname: Smith
            firstname: John
            address: 64 Updown Road
            city: Dublin
    user:
      value:
        data:
          _id: us_693a73206518477283a8d5ae31103252
          email: test@test.com
          roles:
            app_957b12f943d348faa61db7e18e088d0f: BASIC
          builder:
            global: false
          admin:
            global: true
          tenantId: default
          status: active
          budibaseAccess: true
          csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4
          userId: us_693a73206518477283a8d5ae31103252
          roleId: ADMIN
          role:
            _id: ADMIN
            name: Admin
            permissionId: admin
            inherits: POWER
    users:
      value:
        data:
          - _id: us_693a73206518477283a8d5ae31103252
            email: test@test.com
            roles:
              app_957b12f943d348faa61db7e18e088d0f: BASIC
            builder:
              global: false
            admin:
              global: true
            tenantId: default
            status: active
            budibaseAccess: true
            csrfToken: 9c70291d-7137-48f9-9166-99ab5473a3d4
            userId: us_693a73206518477283a8d5ae31103252
            roleId: ADMIN
            role:
              _id: ADMIN
              name: Admin
              permissionId: admin
              inherits: POWER
  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:
    application:
      type: object
      properties:
        name:
          description: The name of the app.
          type: string
        url:
          description: The URL by which the app is accessed, this must be URL encoded.
          type: string
      required:
        - name
        - url
    applicationOutput:
      type: object
      properties:
        data:
          type: object
          properties:
            name:
              description: The name of the app.
              type: string
            url:
              description: The URL by which the app is accessed, this must be URL encoded.
              type: string
            _id:
              description: The ID of the app.
              type: string
            status:
              description: The status of the app, stating it if is the development or
                published version.
              type: string
              enum:
                - development
                - published
            createdAt:
              description: States when the app was created, will be constant. Stored in ISO
                format.
              type: string
            updatedAt:
              description: States the last time the app was updated - stored in ISO format.
              type: string
            version:
              description: States the version of the Budibase client this app is currently
                based on.
              type: string
            tenantId:
              description: In a multi-tenant environment this will state the tenant this app
                is within.
              type: string
            lockedBy:
              description: The user this app is currently being built by.
              type: object
          required:
            - _id
            - name
            - url
            - status
            - createdAt
            - updatedAt
            - version
      required:
        - data
    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
    table:
      description: The table to be created/updated.
      type: object
      required:
        - name
        - schema
      properties:
        name:
          description: The name of the table.
          type: string
        primaryDisplay:
          type: string
          description: The name of the column which should be used in relationship tags
            when relating to this table.
        schema:
          type: object
          additionalProperties:
            oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - link
                    description: A relationship column.
                  constraints:
                    type: object
                    description: A constraint can be applied to the column which will be validated
                      against when a row is saved.
                    properties:
                      type:
                        type: string
                        enum:
                          - string
                          - number
                          - object
                          - boolean
                      presence:
                        type: boolean
                        description: Defines whether the column is required or not.
                  name:
                    type: string
                    description: The name of the column.
                  autocolumn:
                    type: boolean
                    description: Defines whether the column is automatically generated.
                  fieldName:
                    type: string
                    description: The name of the column which a relationship column is related to in
                      another table.
                  tableId:
                    type: string
                    description: The ID of the table which a relationship column is related to.
                  relationshipType:
                    type: string
                    enum:
                      - one-to-many
                      - many-to-one
                      - many-to-many
                    description: Defines the type of relationship that this column will be used for.
                  through:
                    type: string
                    description: When using a SQL table that contains many to many relationships
                      this defines the table the relationships are linked
                      through.
                  foreignKey:
                    type: string
                    description: When using a SQL table that contains a one to many relationship
                      this defines the foreign key.
                  throughFrom:
                    type: string
                    description: When using a SQL table that utilises a through table, this defines
                      the primary key in the through table for this table.
                  throughTo:
                    type: string
                    description: When using a SQL table that utilises a through table, this defines
                      the primary key in the through table for the related
                      table.
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - formula
                    description: A formula column.
                  constraints:
                    type: object
                    description: A constraint can be applied to the column which will be validated
                      against when a row is saved.
                    properties:
                      type:
                        type: string
                        enum:
                          - string
                          - number
                          - object
                          - boolean
                      presence:
                        type: boolean
                        description: Defines whether the column is required or not.
                  name:
                    type: string
                    description: The name of the column.
                  autocolumn:
                    type: boolean
                    description: Defines whether the column is automatically generated.
                  formula:
                    type: string
                    description: Defines a Handlebars or JavaScript formula to use, note that
                      Javascript formulas are expected to be provided in the
                      base64 format.
                  formulaType:
                    type: string
                    enum:
                      - static
                      - dynamic
                    description: Defines whether this is a static or dynamic formula.
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - string
                      - longform
                      - options
                      - number
                      - boolean
                      - array
                      - datetime
                      - attachment
                      - link
                      - formula
                      - auto
                      - json
                      - internal
                    description: Defines the type of the column, most explain themselves, a link
                      column is a relationship.
                  constraints:
                    type: object
                    description: A constraint can be applied to the column which will be validated
                      against when a row is saved.
                    properties:
                      type:
                        type: string
                        enum:
                          - string
                          - number
                          - object
                          - boolean
                      presence:
                        type: boolean
                        description: Defines whether the column is required or not.
                  name:
                    type: string
                    description: The name of the column.
                  autocolumn:
                    type: boolean
                    description: Defines whether the column is automatically generated.
    tableOutput:
      type: object
      properties:
        data:
          description: The table to be created/updated.
          type: object
          required:
            - name
            - schema
            - _id
          properties:
            name:
              description: The name of the table.
              type: string
            primaryDisplay:
              type: string
              description: The name of the column which should be used in relationship tags
                when relating to this table.
            schema:
              type: object
              additionalProperties:
                oneOf:
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - link
                        description: A relationship column.
                      constraints:
                        type: object
                        description: A constraint can be applied to the column which will be validated
                          against when a row is saved.
                        properties:
                          type:
                            type: string
                            enum:
                              - string
                              - number
                              - object
                              - boolean
                          presence:
                            type: boolean
                            description: Defines whether the column is required or not.
                      name:
                        type: string
                        description: The name of the column.
                      autocolumn:
                        type: boolean
                        description: Defines whether the column is automatically generated.
                      fieldName:
                        type: string
                        description: The name of the column which a relationship column is related to in
                          another table.
                      tableId:
                        type: string
                        description: The ID of the table which a relationship column is related to.
                      relationshipType:
                        type: string
                        enum:
                          - one-to-many
                          - many-to-one
                          - many-to-many
                        description: Defines the type of relationship that this column will be used for.
                      through:
                        type: string
                        description: When using a SQL table that contains many to many relationships
                          this defines the table the relationships are linked
                          through.
                      foreignKey:
                        type: string
                        description: When using a SQL table that contains a one to many relationship
                          this defines the foreign key.
                      throughFrom:
                        type: string
                        description: When using a SQL table that utilises a through table, this defines
                          the primary key in the through table for this table.
                      throughTo:
                        type: string
                        description: When using a SQL table that utilises a through table, this defines
                          the primary key in the through table for the related
                          table.
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - formula
                        description: A formula column.
                      constraints:
                        type: object
                        description: A constraint can be applied to the column which will be validated
                          against when a row is saved.
                        properties:
                          type:
                            type: string
                            enum:
                              - string
                              - number
                              - object
                              - boolean
                          presence:
                            type: boolean
                            description: Defines whether the column is required or not.
                      name:
                        type: string
                        description: The name of the column.
                      autocolumn:
                        type: boolean
                        description: Defines whether the column is automatically generated.
                      formula:
                        type: string
                        description: Defines a Handlebars or JavaScript formula to use, note that
                          Javascript formulas are expected to be provided in the
                          base64 format.
                      formulaType:
                        type: string
                        enum:
                          - static
                          - dynamic
                        description: Defines whether this is a static or dynamic formula.
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - string
                          - longform
                          - options
                          - number
                          - boolean
                          - array
                          - datetime
                          - attachment
                          - link
                          - formula
                          - auto
                          - json
                          - internal
                        description: Defines the type of the column, most explain themselves, a link
                          column is a relationship.
                      constraints:
                        type: object
                        description: A constraint can be applied to the column which will be validated
                          against when a row is saved.
                        properties:
                          type:
                            type: string
                            enum:
                              - string
                              - number
                              - object
                              - boolean
                          presence:
                            type: boolean
                            description: Defines whether the column is required or not.
                      name:
                        type: string
                        description: The name of the column.
                      autocolumn:
                        type: boolean
                        description: Defines whether the column is automatically generated.
            _id:
              description: The ID of the table.
              type: string
      required:
        - data
    executeQuery:
      description: The query body must contain the required parameters for the query,
        this depends on query type, setup and bindings.
      type: object
      additionalProperties:
        description: Key value properties of any type, depending on the query output schema.
    executeQueryOutput:
      type: object
      properties:
        data:
          description: The data response from the query.
          type: array
          items:
            type: object
        extra:
          description: Extra information that is not part of the main data, e.g. headers.
          type: object
          properties:
            headers:
              description: If carrying out a REST request, this will contain the response
                headers.
              type: object
            raw:
              description: The raw query response, as a string.
              type: string
        pagination:
          description: If pagination is supported, this will contain the bookmark/anchor
            information for it.
          type: object
      required:
        - data
    query:
      type: object
      properties:
        _id:
          description: The ID of the query.
          type: string
        datasourceId:
          description: The ID of the data source the query belongs to.
          type: string
        parameters:
          description: The bindings which are required to perform this query.
          type: array
          items:
            type: string
        fields:
          description: The fields that are used to perform this query, e.g. the sql
            statement
          type: object
        queryVerb:
          description: The verb that describes this query.
          enum:
            - create
            - read
            - update
            - delete
        name:
          description: The name of the query.
          type: string
        schema:
          description: The schema of the data returned when the query is executed.
          type: object
        transformer:
          description: The JavaScript transformer function, applied after the query
            responds with data.
          type: string
        readable:
          description: Whether the query has readable data.
          type: boolean
      required:
        - name
        - schema
        - _id
    user:
      type: object
      properties:
        email:
          description: The email address of the user, this must be unique.
          type: string
        password:
          description: The password of the user if using password based login - this will
            never be returned. This can be left out of subsequent requests
            (updates) and will be enriched back into the user structure.
          type: string
        status:
          description: The status of the user, if they are active.
          type: string
          enum:
            - active
        firstName:
          description: The first name of the user
          type: string
        lastName:
          description: The last name of the user
          type: string
        forceResetPassword:
          description: If set to true forces the user to reset their password on first
            login.
          type: boolean
        builder:
          description: Describes if the user is a builder user or not.
          type: object
          properties:
            global:
              description: If set to true the user will be able to build any app in the
                system.
              type: boolean
        admin:
          description: Describes if the user is an admin user or not.
          type: object
          properties:
            global:
              description: If set to true the user will be able to administrate the system.
              type: boolean
        roles:
          description: Contains the roles of the user per app (assuming they are not a
            builder user).
          type: object
          additionalProperties:
            type: string
            description: A map of app ID (production app ID, minus the _dev component) to a
              role ID, e.g. ADMIN.
      required:
        - email
        - roles
    userOutput:
      type: object
      properties:
        data:
          type: object
          properties:
            email:
              description: The email address of the user, this must be unique.
              type: string
            password:
              description: The password of the user if using password based login - this will
                never be returned. This can be left out of subsequent requests
                (updates) and will be enriched back into the user structure.
              type: string
            status:
              description: The status of the user, if they are active.
              type: string
              enum:
                - active
            firstName:
              description: The first name of the user
              type: string
            lastName:
              description: The last name of the user
              type: string
            forceResetPassword:
              description: If set to true forces the user to reset their password on first
                login.
              type: boolean
            builder:
              description: Describes if the user is a builder user or not.
              type: object
              properties:
                global:
                  description: If set to true the user will be able to build any app in the
                    system.
                  type: boolean
            admin:
              description: Describes if the user is an admin user or not.
              type: object
              properties:
                global:
                  description: If set to true the user will be able to administrate the system.
                  type: boolean
            roles:
              description: Contains the roles of the user per app (assuming they are not a
                builder user).
              type: object
              additionalProperties:
                type: string
                description: A map of app ID (production app ID, minus the _dev component) to a
                  role ID, e.g. ADMIN.
            _id:
              description: The ID of the user.
              type: string
          required:
            - email
            - roles
            - _id
      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
security:
  - ApiKeyAuth: []
paths:
  /applications:
    post:
      summary: Create an application
      tags:
        - applications
      parameters:
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/application"
      responses:
        "200":
          description: Returns the created application.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationOutput"
              examples:
                application:
                  $ref: "#/components/examples/application"
  "/applications/{appId}":
    put:
      summary: Update an application
      tags:
        - applications
      parameters:
        - $ref: "#/components/parameters/appIdUrl"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/application"
      responses:
        "200":
          description: Returns the updated application.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationOutput"
              examples:
                application:
                  $ref: "#/components/examples/application"
    delete:
      summary: Delete an application
      tags:
        - applications
      parameters:
        - $ref: "#/components/parameters/appIdUrl"
      responses:
        "200":
          description: Returns the deleted application.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationOutput"
              examples:
                application:
                  $ref: "#/components/examples/application"
    get:
      summary: Retrieve an application
      tags:
        - applications
      parameters:
        - $ref: "#/components/parameters/appIdUrl"
      responses:
        "200":
          description: Returns the retrieved application.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/applicationOutput"
              examples:
                application:
                  $ref: "#/components/examples/application"
  /applications/search:
    post:
      summary: Search for applications
      description: Based on application properties (currently only name) search for
        applications.
      tags:
        - applications
      parameters:
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/nameSearch"
      responses:
        "200":
          description: Returns the applications that were found based on the search
            parameters.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/application"
              examples:
                applications:
                  $ref: "#/components/examples/applications"
  "/queries/{queryId}":
    post:
      summary: Execute a query
      description: Queries which have been created within a Budibase app can be
        executed using this,
      tags:
        - queries
      parameters:
        - $ref: "#/components/parameters/queryId"
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/executeQuery"
      responses:
        "200":
          description: Returns the result of the query execution.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/executeQueryOutput"
              examples:
                REST:
                  $ref: "#/components/examples/restResponse"
                SQL:
                  $ref: "#/components/examples/sqlResponse"
  /queries/search:
    post:
      summary: Search for queries
      description: Based on query properties (currently only name) search for queries.
      tags:
        - queries
      parameters:
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/nameSearch"
      responses:
        "200":
          description: Returns the queries found based on the search parameters.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/query"
              examples:
                queries:
                  $ref: "#/components/examples/queries"
  "/tables/{tableId}/rows":
    post:
      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"
  "/tables/{tableId}/rows/{rowId}":
    put:
      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"
    delete:
      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"
    get:
      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"
  "/tables/{tableId}/rows/search":
    post:
      summary: Search for rows
      tags:
        - rows
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              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:
                $ref: "#/components/schemas/searchOutput"
              examples:
                search:
                  $ref: "#/components/examples/rows"
  /tables:
    post:
      summary: Create a table
      description: Create a table, this could be internal or external.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/appId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/table"
            examples:
              table:
                $ref: "#/components/examples/table"
      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:
                $ref: "#/components/schemas/tableOutput"
              examples:
                table:
                  $ref: "#/components/examples/table"
  "/tables/{tableId}":
    put:
      summary: Update a table
      description: Update a table, this could be internal or external.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/table"
            examples:
              table:
                $ref: "#/components/examples/table"
      responses:
        "200":
          description: Returns the updated table.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tableOutput"
              examples:
                table:
                  $ref: "#/components/examples/table"
    delete:
      summary: Delete a table
      description: Delete a table, this could be internal or external.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      responses:
        "200":
          description: Returns the deleted table.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tableOutput"
              examples:
                table:
                  $ref: "#/components/examples/table"
    get:
      summary: Retrieve a table
      description: Lookup a table, this could be internal or external.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/tableId"
        - $ref: "#/components/parameters/appId"
      responses:
        "200":
          description: Returns the retrieved table.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/tableOutput"
              examples:
                table:
                  $ref: "#/components/examples/table"
  /tables/search:
    post:
      summary: Search for tables
      description: Based on table properties (currently only name) search for tables.
        This could be an internal or an external table.
      tags:
        - tables
      parameters:
        - $ref: "#/components/parameters/appId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/nameSearch"
      responses:
        "200":
          description: Returns the found tables, based on the search parameters.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/table"
              examples:
                tables:
                  $ref: "#/components/examples/tables"
  /users:
    post:
      summary: Create a user
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        "200":
          description: Returns the created user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/userOutput"
              examples:
                user:
                  $ref: "#/components/examples/user"
  "/users/{userId}":
    put:
      summary: Update a user
      tags:
        - users
      parameters:
        - $ref: "#/components/parameters/userId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/user"
      responses:
        "200":
          description: Returns the updated user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/userOutput"
              examples:
                user:
                  $ref: "#/components/examples/user"
    delete:
      summary: Delete a user
      tags:
        - users
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: Returns the deleted user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/userOutput"
              examples:
                user:
                  $ref: "#/components/examples/user"
    get:
      summary: Retrieve a user
      tags:
        - users
      parameters:
        - $ref: "#/components/parameters/userId"
      responses:
        "200":
          description: Returns the retrieved user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/userOutput"
              examples:
                user:
                  $ref: "#/components/examples/user"
  /users/search:
    post:
      summary: Search for users
      description: Based on user properties (currently only name) search for users.
      tags:
        - users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/nameSearch"
      responses:
        "200":
          description: Returns the found users based on search parameters.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/user"
              examples:
                users:
                  $ref: "#/components/examples/users"
tags: []