Quickbase Tables API

openapi: 3.2.0
info:
  title: Quickbase Tables API
  version: 1.0.0
  description: 'Operations tagged Tables across 2 of this provider''s published API definitions: qb-openapi-v3.json, quickbase-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.quickbase.com/v1
tags:
- name: Tables
paths:
  /tables:
    get:
      tags:
      - Tables
      summary: Get tables for an app
      description: Gets a list of all the tables that exist in a specific application. The properties for each table are the same as what is returned in Get table.
      operationId: getAppTables
      parameters:
      - $ref: '#/components/parameters/queryAppId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                example:
                - name: 'Example Table #0'
                  created: '2020-03-27T18:34:40.000Z'
                  updated: '2020-04-03T19:12:40.000Z'
                  alias: _dbid_example_table_#0
                  description: Table zero as an example.
                  id: bpqe82s1
                  nextRecordId: 1
                  nextFieldId: 1
                  defaultSortFieldId: 2
                  defaultSortOrder: ASC
                  keyFieldId: 3
                  singleRecordName: Example Record
                  pluralRecordName: Example Records
                  sizeLimit: 150 MB
                  spaceUsed: 17 MB
                  spaceRemaining: 133 MB
                - name: 'Example Table #2'
                  created: '2020-03-27T18:34:40.000Z'
                  updated: '2020-04-03T19:12:40.000Z'
                  alias: _dbid_example_table_#2
                  description: Table two as an example.
                  id: bpqe82z1
                  nextRecordId: 10
                  nextFieldId: 111
                  defaultSortFieldId: 12
                  defaultSortOrder: DESC
                  keyFieldId: 33
                  singleRecordName: Another Record
                  pluralRecordName: More Records
                  sizeLimit: 150 MB
                  spaceUsed: 22 MB
                  spaceRemaining: 128 MB
                items:
                  $ref: '#/components/schemas/tableResponse'
    post:
      tags:
      - Tables
      summary: Create a table
      description: Creates a table in an application.
      operationId: createTable
      parameters:
      - $ref: '#/components/parameters/queryAppId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/tableInput'
              - required:
                - name
                type: object
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tableResponse'
    servers:
    - url: https://api.quickbase.com/v1
  /tables/{tableId}:
    get:
      tags:
      - Tables
      summary: Get a table
      description: Gets the properties of an individual table that is part of an application.
      operationId: getTable
      parameters:
      - $ref: '#/components/parameters/queryAppId'
      - $ref: '#/components/parameters/pathTableId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tableResponse'
    post:
      tags:
      - Tables
      summary: Update a table
      description: Updates the main properties of a specific table. Any properties of the table that you do not specify in the request body will remain unchanged.
      operationId: updateTable
      parameters:
      - $ref: '#/components/parameters/queryAppId'
      - $ref: '#/components/parameters/pathTableId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tableInput'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tableResponse'
    delete:
      tags:
      - Tables
      summary: Delete a table
      description: Deletes a specific table in an application, including all of the data within it.
      operationId: deleteTable
      parameters:
      - $ref: '#/components/parameters/queryAppId'
      - $ref: '#/components/parameters/pathTableId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedTableId:
                    description: The deleted table id.
                    type: string
                example:
                  deletedTableId: bck7gp3q2
    servers:
    - url: https://api.quickbase.com/v1
  /tables/{tableId}/relationships:
    get:
      tags:
      - Tables
      summary: Get all relationships
      description: Get a list of all relationships, and their definitions, for a specific table. Details are provided for the child side of relationships within a given application. Limited details are returned for cross-application relationships.
      operationId: getRelationships
      parameters:
      - name: skip
        in: query
        description: The number of relationships to skip.
        schema:
          type: integer
        example: 5
      - $ref: '#/components/parameters/pathTableIdChild'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - relationships
                properties:
                  relationships:
                    description: The relationships in a table.
                    type: array
                    items:
                      $ref: '#/components/schemas/relationshipResponse'
                  metadata:
                    description: Additional information about the results that may be helpful.
                    type: object
                    properties:
                      skip:
                        description: The number of relationships to skip.
                        type: integer
                      totalRelationships:
                        description: The total number of relationships.
                        type: integer
                      numRelationships:
                        description: The number of relationships in the current response object.
                        type: integer
                example:
                  metadata:
                    numRelationships: 1
                    skip: 0
                    totalRelationships: 1
                  relationships:
                  - childTableId: bqqjnwsuy
                    foreignKeyField:
                      id: 6
                      label: Related record
                      type: numeric
                    id: 6
                    isCrossApp: false
                    lookupFields:
                    - id: 3
                      label: Name
                      type: text
                    parentTableId: bck7gp3q2
                    summaryFields:
                    - id: 8
                      label: my summary field
                      type: numeric
    servers:
    - url: https://api.quickbase.com/v1
  /tables/{tableId}/relationship:
    post:
      tags:
      - Tables
      summary: Create a relationship
      description: Creates a relationship in a table as well as lookup/summary fields. Relationships can only be created for tables within the same app.
      operationId: createRelationship
      parameters:
      - $ref: '#/components/parameters/pathTableIdChild'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createRelationshipInput'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/relationshipResponse'
    servers:
    - url: https://api.quickbase.com/v1
  /tables/{tableId}/relationship/{relationshipId}:
    post:
      tags:
      - Tables
      summary: Update a relationship
      description: Use this endpoint to add lookup fields and summary fields to an existing relationship. Updating a relationship will not delete existing lookup/summary fields.
      operationId: updateRelationship
      parameters:
      - $ref: '#/components/parameters/pathTableIdChild'
      - $ref: '#/components/parameters/pathRelationshipId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateRelationshipInput'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/relationshipResponse'
    delete:
      tags:
      - Tables
      summary: Delete a relationship
      description: Use this endpoint to delete an entire relationship, including all lookup and summary fields. The reference field in the relationship will not be deleted.
      operationId: deleteRelationship
      parameters:
      - $ref: '#/components/parameters/pathTableIdChild'
      - $ref: '#/components/parameters/pathRelationshipId'
      - $ref: '#/components/parameters/qbRealmHostname'
      - $ref: '#/components/parameters/userAgent'
      - $ref: '#/components/parameters/authorization'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  relationshipId:
                    description: The relationship id.
                    type: integer
                example:
                  relationshipId: 6
    servers:
    - url: https://api.quickbase.com/v1
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      description: The Quickbase authentication scheme you are using to authenticate the request, as described on the [authorization page](../auth).
      required: true
      schema:
        type: string
      example: QB-USER-TOKEN xxxxxx_xxx_xxxxxxxxxxxxxxxxxxxxxxx
    pathTableIdChild:
      name: tableId
      in: path
      description: The unique identifier (dbid) of the child table.
      required: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/tableIdSimple'
    qbRealmHostname:
      name: QB-Realm-Hostname
      in: header
      description: Your Quickbase domain, for example demo.quickbase.com
      required: true
      schema:
        type: string
      example: demo.quickbase.com
    pathRelationshipId:
      name: relationshipId
      in: path
      description: The relationship id. This is the field id of the reference field on the child table.
      required: true
      schema:
        type: number
      example: 6
    queryAppId:
      name: appId
      in: query
      description: The unique identifier of an app
      required: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/appId'
    userAgent:
      name: User-Agent
      in: header
      description: This is entered by the person or utility invoking the API. You might custom create this or use the default one of your toolkit. Being descriptive here may offer more identification and troubleshooting capabilities.
      schema:
        type: string
      example: FileService_Integration_V2.1
    pathTableId:
      name: tableId
      in: path
      description: The unique identifier (dbid) of the table.
      required: true
      allowReserved: true
      schema:
        $ref: '#/components/schemas/tableIdSimple'
  schemas:
    updateRelationshipInput:
      type: object
      properties:
        summaryFields:
          type: array
          description: An array of objects, each representing a configuration of one field from the child table, that will become summary fields on the parent table. When you specify the 'COUNT' accumulation type, you have to specify 0 as the summaryFid (or not set it in the request). 'DISTINCT-COUNT' requires that summaryFid be set to an actual fid.
          items:
            required:
            - accumulationType
            type: object
            properties:
              summaryFid:
                type: number
                description: The field id to summarize.
              label:
                type: string
                description: The label for the summary field.
              accumulationType:
                type: string
                description: The accumulation type for the summary field.
                enum:
                - AVG
                - SUM
                - MAX
                - MIN
                - STD-DEV
                - COUNT
                - COMBINED-TEXT
                - COMBINED-USER
                - DISTINCT-COUNT
              where:
                type: string
                description: The filter, using the Quickbase query language, which determines the records to return.
        lookupFieldIds:
          type: array
          description: An array of field IDs in the parent table that will become lookup fields in the child table.
          items:
            type: integer
      example:
        lookupFieldIds:
        - 4
        - 5
        - 6
        summaryFields:
        - summaryFid: 3
          label: my summary field
          accumulationType: COUNT
          where: '{''3''.EX.1}'
    appId:
      type: string
      pattern: ^\w+$
      description: The unique identifier (dbid) of the app.
      example: bck7gp3q2
    tableResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the table.
        id:
          type: string
          description: The unique identifier (dbid) of the table.
        alias:
          type: string
          description: The automatically-created table alias for the table.
        description:
          type: string
          description: The description of the table, as configured by an application administrator.
        created:
          type: string
          description: The time and date when the table was created, in the ISO 8601 time format YYYY-MM-DDThh:mm:ss.sssZ (in UTC time zone).
        updated:
          type: string
          description: The time and date when the table schema or data was last updated, in the ISO 8601 time format YYYY-MM-DDThh:mm:ss.sssZ (in UTC time zone).
        nextRecordId:
          type: integer
          description: The incremental Record ID that will be used when the next record is created, as determined when the API call was ran.
        nextFieldId:
          type: integer
          description: The incremental Field ID that will be used when the next field is created, as determined when the API call was ran.
        defaultSortFieldId:
          type: integer
          description: The id of the field that is configured for default sorting.
        defaultSortOrder:
          type: string
          description: The configuration of the default sort order on the table.
          enum:
          - ASC
          - DESC
        keyFieldId:
          type: integer
          description: The id of the field that is configured to be the key on this table, which is usually the Quickbase Record ID.
        singleRecordName:
          type: string
          description: The builder-configured singular noun of the table.
        pluralRecordName:
          type: string
          description: The builder-configured plural noun of the table.
        sizeLimit:
          type: string
          description: The size limit for the table.
        spaceUsed:
          type: string
          description: The amount of space currently being used by the table.
        spaceRemaining:
          type: string
          description: The amount of space remaining for use by the table.
      example:
        name: Example Table
        created: '2020-03-27T18:34:40.000Z'
        updated: '2020-04-03T19:12:40.000Z'
        alias: _dbid_example_table
        description: Table as an example.
        id: bpqe82s0
        nextRecordId: 1
        nextFieldId: 1
        defaultSortFieldId: 2
        defaultSortOrder: ASC
        keyFieldId: 3
        singleRecordName: Example Record
        pluralRecordName: Example Records
        sizeLimit: 150 MB
        spaceUsed: 17 MB
        spaceRemaining: 133 MB
    tableInput:
      type: object
      properties:
        name:
          type: string
          description: The name for the table.
        pluralRecordName:
          type: string
          description: The plural noun for records in the table. If this value is not passed the default value is 'Records'.
        singleRecordName:
          type: string
          description: The singular noun for records in the table. If this value is not passed the default value is 'Record'.
        description:
          type: string
          description: The description for the table. If this value is not passed the default value is blank.
      description: The example below shows all the properties that can be changed with this request. Additional properties that you can see with the corresponding GET request cannot be set through this API.
      example:
        name: My table
        description: my first table
        singleRecordName: record
        pluralRecordName: records
    tableIdSimple:
      type: string
      pattern: ^\w+$
      description: The unique identifier (dbid) of the table.
      example: bck7gp3q2
    relationshipResponse:
      type: object
      required:
      - id
      - parentTableId
      - childTableId
      - isCrossApp
      properties:
        id:
          description: The relationship id (foreign key field id).
          type: integer
        parentTableId:
          description: The parent table id of the relationship.
          type: string
        childTableId:
          description: The child table id of the relationship.
          type: string
        foreignKeyField:
          description: The foreign key field information.
          type: object
          properties:
            id:
              description: Field id.
              type: integer
            label:
              description: Field label.
              type: string
            type:
              description: Field type.
              type: string
        isCrossApp:
          description: Whether this is a cross-app relationship.
          type: boolean
        lookupFields:
          description: The lookup fields array.
          type: array
          items:
            type: object
            properties:
              id:
                description: Field id.
                type: integer
              label:
                description: Field label.
                type: string
              type:
                description: Field type.
                type: string
        summaryFields:
          description: The summary fields array.
          type: array
          items:
            type: object
            properties:
              id:
                description: Field id.
                type: integer
              label:
                description: Field label.
                type: string
              type:
                description: Field type.
                type: string
      example:
        id: 6
        foreignKeyField:
          id: 6
          label: Related record
          type: numeric
        lookupFields:
        - id: 7
          label: record - text field
          type: text
        isCrossApp: false
        parentTableId: bck7gp3q2
        childTableId: bck7gp3q3
        summaryFields:
        - id: 8
          label: Summary of Record ID#2
          type: numeric
    createRelationshipInput:
      allOf:
      - $ref: '#/components/schemas/updateRelationshipInput'
      - required:
        - parentTableId
        type: object
        properties:
          parentTableId:
            type: string
            description: The parent table id for the relationship.
          foreignKeyField:
            type: object
            properties:
              label:
                type: string
                description: The label for the foreign key field.
            description: This property is optional. If it is not provided, the foreign key field will be created with the label 'Related <record>', where <record> is the name of a record in the parent table.
      example:
        parentTableId: bck7gp3q2
        foreignKeyField:
          label: my relationship field
        lookupFieldIds:
        - 1
        - 2
        - 3
        summaryFields:
        - summaryFid: 3
          label: my first summary field
          accumulationType: AVG
          where: '{''3''.EX.1}'
        - summaryFid: 4
          label: my second summary field
          accumulationType: SUM
x-refined-from:
- qb-openapi-v3.json
- quickbase-openapi.yml