HubSpot CMS HubDB API

openapi: 3.1.0
info:
  title: HubSpot CMS HubDB API
  description: >-
    The HubDB API allows you to create, update, and delete HubDB data tables and
    their rows. HubDB tables can be used as data sources for dynamic CMS pages
    and are available in both draft and published versions. Each table has a
    live version and a draft version that can be edited and published independently.
  version: v3
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com/
servers:
- url: https://api.hubapi.com
  description: HubSpot API
security:
- oauth2: []
tags:
- name: Rows
  description: Operations for managing HubDB table rows
- name: Tables
  description: Operations for managing HubDB tables
paths:
  /cms/v3/hubdb/tables:
    get:
      operationId: listHubDBTables
      summary: Hubspot List Hubdb Tables
      description: >-
        Returns a list of all HubDB tables in the portal. Each table entry
        includes metadata such as the table name, label, column definitions,
        and publish status. Both published and draft tables are accessible
        through this endpoint.
      tags:
      - Tables
      parameters:
      - name: sort
        in: query
        description: Field to sort results by.
        schema:
          type: string
        example: example-value
      - name: after
        in: query
        description: The cursor for pagination to get the next page of results.
        schema:
          type: string
        example: example-value
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        schema:
          type: integer
        example: 100
      - name: createdAt
        in: query
        description: Filter tables created at this timestamp.
        schema:
          type: string
          format: date-time
        example: '2025-03-15T14:30:00Z'
      - name: updatedAt
        in: query
        description: Filter tables updated at this timestamp.
        schema:
          type: string
          format: date-time
        example: '2025-03-15T14:30:00Z'
      responses:
        '200':
          description: Successful response with a list of HubDB tables.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseHubDBTable'
              examples:
                Listhubdbtables200Example:
                  summary: Default listHubDBTables 200 response
                  x-microcks-default: true
                  value:
                    results: &id005
                    - id: '500123'
                      name: Example Record
                      label: Example Record
                      columns: &id001
                      - id: '500123'
                        name: Example Record
                        label: Example Record
                        type: TEXT
                        options:
                        - {}
                      published: true
                      rowCount: 10
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      publishedAt: '2025-03-15T14:30:00Z'
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createHubDBTable
      summary: Hubspot Create a Hubdb Table
      description: >-
        Creates a new HubDB table with the specified name, label, and column
        definitions. The new table starts in draft state and must be published
        to make it available for CMS page use.
      tags:
      - Tables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubDBTableCreateRequest'
            examples:
              CreatehubdbtableRequestExample:
                summary: Default createHubDBTable request
                x-microcks-default: true
                value:
                  name: Example Record
                  label: Example Record
                  columns: &id002
                  - name: Example Record
                    label: Example Record
                    type: standard
      responses:
        '201':
          description: Table created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBTable'
              examples:
                Createhubdbtable201Example:
                  summary: Default createHubDBTable 201 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    name: Example Record
                    label: Example Record
                    columns: *id001
                    published: true
                    rowCount: 10
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    publishedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cms/v3/hubdb/tables/{tableIdOrName}:
    get:
      operationId: getHubDBTable
      summary: Hubspot Get a Hubdb Table
      description: >-
        Returns the details of a specific HubDB table identified by its ID
        or name, including column definitions, publish status, and metadata.
      tags:
      - Tables
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table to retrieve.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response with the HubDB table details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBTable'
              examples:
                Gethubdbtable200Example:
                  summary: Default getHubDBTable 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    name: Example Record
                    label: Example Record
                    columns: *id001
                    published: true
                    rowCount: 10
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    publishedAt: '2025-03-15T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateHubDBTable
      summary: Hubspot Update a Hubdb Table
      description: >-
        Updates an existing HubDB table's metadata, label, or column
        definitions. Updates are applied to the draft version of the table
        and must be published to take effect on live pages.
      tags:
      - Tables
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table to update.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubDBTableCreateRequest'
            examples:
              UpdatehubdbtableRequestExample:
                summary: Default updateHubDBTable request
                x-microcks-default: true
                value:
                  name: Example Record
                  label: Example Record
                  columns: *id002
      responses:
        '200':
          description: Table updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBTable'
              examples:
                Updatehubdbtable200Example:
                  summary: Default updateHubDBTable 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    name: Example Record
                    label: Example Record
                    columns: *id001
                    published: true
                    rowCount: 10
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    publishedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteHubDBTable
      summary: Hubspot Delete a Hubdb Table
      description: >-
        Permanently deletes a HubDB table and all its rows. This action cannot
        be undone. Deleting a table that is used by CMS pages may break those
        pages.
      tags:
      - Tables
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table to delete.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Table deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cms/v3/hubdb/tables/{tableIdOrName}/rows:
    get:
      operationId: listHubDBTableRows
      summary: Hubspot List Hubdb Table Rows
      description: >-
        Returns the rows of a specific HubDB table. By default, returns
        rows from the published version of the table. Use the draft parameter
        to retrieve rows from the draft version.
      tags:
      - Rows
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table.
        schema:
          type: string
        example: '500123'
      - name: sort
        in: query
        description: Column to sort results by.
        schema:
          type: string
        example: example-value
      - name: after
        in: query
        description: The cursor for pagination to get the next page of results.
        schema:
          type: string
        example: example-value
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        schema:
          type: integer
        example: 100
      - name: properties
        in: query
        description: A comma-separated list of column names to return.
        schema:
          type: string
        example: example-value
      responses:
        '200':
          description: Successful response with the table rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseHubDBRow'
              examples:
                Listhubdbtablerows200Example:
                  summary: Default listHubDBTableRows 200 response
                  x-microcks-default: true
                  value:
                    results: &id006
                    - id: '500123'
                      values: &id003
                        key: value
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addHubDBTableRow
      summary: Hubspot Add a Row to a Hubdb Table
      description: >-
        Adds a new row to a HubDB table. The row data is added to the draft
        version of the table. Publish the table draft to make the new row
        visible on live pages.
      tags:
      - Rows
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table to add a row to.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubDBRowCreateRequest'
            examples:
              AddhubdbtablerowRequestExample:
                summary: Default addHubDBTableRow request
                x-microcks-default: true
                value:
                  values: &id004
                    key: value
      responses:
        '201':
          description: Row added successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBRow'
              examples:
                Addhubdbtablerow201Example:
                  summary: Default addHubDBTableRow 201 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    values: *id003
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cms/v3/hubdb/tables/{tableIdOrName}/rows/{rowId}:
    get:
      operationId: getHubDBTableRow
      summary: Hubspot Get a Hubdb Table Row
      description: >-
        Returns a specific row from a HubDB table by its row ID. Returns
        the published version of the row by default.
      tags:
      - Rows
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table.
        schema:
          type: string
        example: '500123'
      - name: rowId
        in: path
        required: true
        description: The ID of the row to retrieve.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response with the row details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBRow'
              examples:
                Gethubdbtablerow200Example:
                  summary: Default getHubDBTableRow 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    values: *id003
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateHubDBTableRow
      summary: Hubspot Update a Hubdb Table Row
      description: >-
        Performs a partial update of a specific HubDB table row. Only the
        columns included in the request body will be updated. Changes are
        applied to the draft version and must be published.
      tags:
      - Rows
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table.
        schema:
          type: string
        example: '500123'
      - name: rowId
        in: path
        required: true
        description: The ID of the row to update.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubDBRowCreateRequest'
            examples:
              UpdatehubdbtablerowRequestExample:
                summary: Default updateHubDBTableRow request
                x-microcks-default: true
                value:
                  values: *id004
      responses:
        '200':
          description: Row updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBRow'
              examples:
                Updatehubdbtablerow200Example:
                  summary: Default updateHubDBTableRow 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    values: *id003
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteHubDBTableRow
      summary: Hubspot Delete a Hubdb Table Row
      description: >-
        Permanently deletes a row from a HubDB table. The deletion is applied
        to the draft version and must be published to remove the row from live
        pages.
      tags:
      - Rows
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table.
        schema:
          type: string
        example: '500123'
      - name: rowId
        in: path
        required: true
        description: The ID of the row to delete.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Row deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cms/v3/hubdb/tables/{tableIdOrName}/draft/push-live:
    post:
      operationId: publishHubDBTableDraft
      summary: Hubspot Publish Hubdb Table Draft
      description: >-
        Publishes the draft version of a HubDB table, making all pending
        changes to the table structure and rows live. After publishing,
        the draft and live versions are synchronized.
      tags:
      - Tables
      parameters:
      - name: tableIdOrName
        in: path
        required: true
        description: The ID or name of the HubDB table to publish.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Table draft published successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubDBTable'
              examples:
                Publishhubdbtabledraft200Example:
                  summary: Default publishHubDBTableDraft 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    name: Example Record
                    label: Example Record
                    columns: *id001
                    published: true
                    rowCount: 10
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    publishedAt: '2025-03-15T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (access token from OAuth flow)
  schemas:
    HubDBTable:
      type: object
      description: A HubDB table.
      properties:
        id:
          type: string
          description: The unique identifier for the table.
          example: '500123'
        name:
          type: string
          description: The machine-readable name of the table.
          example: Example Record
        label:
          type: string
          description: The human-readable label for the table.
          example: Example Record
        columns:
          type: array
          description: The column definitions for the table.
          items:
            $ref: '#/components/schemas/HubDBColumn'
          example: *id001
        published:
          type: boolean
          description: Whether the table has been published.
          example: true
        rowCount:
          type: integer
          description: The number of rows in the published table.
          example: 10
        createdAt:
          type: string
          format: date-time
          description: The date and time the table was created.
          example: '2025-03-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time the table was last updated.
          example: '2025-03-15T14:30:00Z'
        publishedAt:
          type: string
          format: date-time
          description: The date and time the table was last published.
          example: '2025-03-15T14:30:00Z'
    HubDBColumn:
      type: object
      description: A column definition in a HubDB table.
      properties:
        id:
          type: string
          description: The unique identifier for the column.
          example: '500123'
        name:
          type: string
          description: The machine-readable name of the column.
          example: Example Record
        label:
          type: string
          description: The human-readable label for the column.
          example: Example Record
        type:
          type: string
          description: The data type of the column.
          enum: [TEXT, NUMBER, URL, IMAGE, SELECT, MULTISELECT, BOOLEAN, LOCATION, DATE, DATETIME, CURRENCY, RICHTEXT, FOREIGN_ID]
          example: TEXT
        options:
          type: array
          description: Available options for SELECT and MULTISELECT columns.
          items:
            type: object
          example:
          - {}
    HubDBTableCreateRequest:
      type: object
      description: Request body for creating or updating a HubDB table.
      required:
      - name
      - label
      properties:
        name:
          type: string
          description: The machine-readable name of the table.
          example: Example Record
        label:
          type: string
          description: The human-readable label for the table.
          example: Example Record
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              label:
                type: string
              type:
                type: string
          example: *id002
    HubDBRow:
      type: object
      description: A row in a HubDB table.
      properties:
        id:
          type: string
          description: The unique identifier for the row.
          example: '500123'
        values:
          type: object
          description: The column values for the row as key-value pairs.
          additionalProperties: true
          example: *id003
        createdAt:
          type: string
          format: date-time
          description: The date and time the row was created.
          example: '2025-03-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time the row was last updated.
          example: '2025-03-15T14:30:00Z'
    HubDBRowCreateRequest:
      type: object
      description: Request body for creating or updating a HubDB table row.
      properties:
        values:
          type: object
          description: The column values for the row as key-value pairs.
          additionalProperties: true
          example: *id004
    CollectionResponseHubDBTable:
      type: object
      description: A paginated list of HubDB tables.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/HubDBTable'
          example: *id005
        paging:
          $ref: '#/components/schemas/Paging'
    CollectionResponseHubDBRow:
      type: object
      description: A paginated list of HubDB table rows.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/HubDBRow'
          example: *id006
        paging:
          $ref: '#/components/schemas/Paging'
    Paging:
      type: object
      description: Pagination information.
      properties:
        next:
          type: object
          properties:
            after:
              type: string
          example:
            after: example-value
    Error:
      type: object
      description: An error response.
      properties:
        status:
          type: string
          example: active
        message:
          type: string
          example: This is an example description.
        correlationId:
          type: string
          example: '500123'
        category:
          type: string
          example: standard
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'