openapi: 3.2.0
info:
  title: Pipeshub Knowledge Hub API
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
  description: 'Operations tagged Knowledge Hub across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Knowledge Hub
  description: Unified browse API for root and child nodes (apps, record groups, folders, records) with filtering and search
paths:
  /knowledgeBase/knowledge-hub/nodes:
    get:
      deprecated: true
      x-speakeasy-deprecation-message: Use the Knowledge Base API instead. This grouping will be removed in a future release
      tags:
      - Knowledge Hub
      summary: Get knowledge hub root nodes
      description: 'Returns root-level nodes (connector apps and Collection apps) or, when

        filters or search are applied, a flat list of matching nodes across the

        entire knowledge hub tree.


        **Overview**


        The Knowledge Hub provides a unified view across all knowledge sources:

        - **Collection** — locally uploaded knowledge bases (`origin: COLLECTION`)

        - **Connector app** — external connector instances such as Google Drive,

        Slack, Confluence, Jira (`origin: CONNECTOR`)


        Use this endpoint to build file-browser UIs and sidebar navigation trees.


        **Browsing vs. searching**


        When no filters or search query are provided, only top-level app nodes

        are returned. Adding `nodeTypes`, `q`, or other filter params triggers a

        search across the full tree, returning matching nodes regardless of depth.


        For children of a specific node, use

        `GET /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}`.


        **Pagination and sorting**


        Results are always paginated. Default sort is `updatedAt` descending.

        The `pagination` object in the response contains `hasNext` / `hasPrev`

        flags suitable for infinite-scroll or page-based navigation.


        **Expanding the response**


        Use the `include` parameter to request additional sections:

        - `availableFilters` — adds `filters.available` with all filter options

        - `counts` — adds a `counts` summary broken down by node type

        - `breadcrumbs` — adds the breadcrumb trail (empty at root level)

        - `permissions` — adds the caller''s permission flags


        **Access control**


        Requires a valid bearer token. For OAuth tokens the `kb:read` scope

        must be present; regular JWT bearer tokens pass through without scope

        enforcement.'
      operationId: getKnowledgeHubRootNodes
      x-pipeshub-sdk: true
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: onlyContainers
        in: query
        required: false
        description: 'When `true`, only nodes that have children are returned (useful for

          building sidebar / tree navigation). Leaf nodes are excluded.

          '
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        required: false
        description: 'Page number (1-indexed). Combined with `limit` to paginate results.

          '
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: 'Maximum number of items to return per page.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: sortBy
        in: query
        required: false
        description: 'Field to sort results by. Omitted → default `updatedAt`.

          Unknown value → silently falls back to `name`.

          '
        schema:
          type: string
          enum:
          - name
          - createdAt
          - updatedAt
          - size
          - type
          default: updatedAt
      - name: sortOrder
        in: query
        required: false
        description: 'Sort direction. Omitted → default `desc`.

          Unknown value → silently falls back to `asc`.

          '
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: q
        in: query
        required: false
        description: 'Full-text search query. Must be between 2 and 500 characters

          (inclusive). When provided, the endpoint searches across the entire

          node tree regardless of the current browse level.

          '
        schema:
          type: string
          minLength: 2
          maxLength: 500
        example: quarterly report
      - name: nodeTypes
        in: query
        required: false
        description: 'Comma-separated list of node types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `folder`, `app`, `recordGroup`, `record`

          '
        schema:
          type: string
        example: app,recordGroup
      - name: recordTypes
        in: query
        required: false
        description: 'Comma-separated list of record types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `FILE`, `DRIVE`, `WEBPAGE`, `DATABASE`, `DATASOURCE`,

          `MESSAGE`, `MAIL`, `GROUP_MAIL`, `TICKET`, `COMMENT`,

          `INLINE_COMMENT`, `CONFLUENCE_PAGE`, `CONFLUENCE_BLOGPOST`,

          `SHAREPOINT_PAGE`, `SHAREPOINT_LIST`, `SHAREPOINT_LIST_ITEM`,

          `SHAREPOINT_DOCUMENT_LIBRARY`, `LINK`, `PROJECT`, `PULL_REQUEST`,

          `MEETING`, `PRODUCT`, `DEAL`, `CASE`, `TASK`, `ARTIFACT`,

          `CODE_FILE`, `SQL_TABLE`, `SQL_VIEW`, `OTHERS`

          '
        schema:
          type: string
        example: FILE,CONFLUENCE_PAGE
      - name: origins
        in: query
        required: false
        description: 'Comma-separated list of origin types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `COLLECTION`, `CONNECTOR`

          '
        schema:
          type: string
        example: CONNECTOR
      - name: connectorIds
        in: query
        required: false
        description: 'Comma-separated list of connector instance IDs (UUIDs) to filter by.

          Maximum 100 items. No enum validation — any string is accepted, but

          non-existent IDs simply yield zero results.

          '
        schema:
          type: string
        example: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
      - name: indexingStatus
        in: query
        required: false
        description: 'Comma-separated list of indexing statuses to include. Invalid values

          are silently ignored. Maximum 100 items.


          Valid values: `NOT_STARTED`, `PAUSED`, `IN_PROGRESS`, `COMPLETED`,

          `FAILED`, `FILE_TYPE_NOT_SUPPORTED`, `AUTO_INDEX_OFF`, `EMPTY`,

          `ENABLE_MULTIMODAL_MODELS`, `QUEUED`

          '
        schema:
          type: string
        example: COMPLETED,FAILED
      - name: createdAt
        in: query
        required: false
        description: 'Created-date range filter. Format: `gte:<epochMs>,lte:<epochMs>`.

          Both bounds are optional (you may send just `gte:...` or just

          `lte:...`). Timestamps must be in the range 0 to 9999999999999 and

          `gte` must be less than or equal to `lte` when both are present.

          '
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: updatedAt
        in: query
        required: false
        description: 'Updated-date range filter. Same format and constraints as `createdAt`.

          '
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: size
        in: query
        required: false
        description: 'File-size range filter in bytes. Format: `gte:<bytes>,lte:<bytes>`.

          Both bounds are optional. Values must be non-negative and at most

          1099511627776 (1 TB). `gte` must be less than or equal to `lte`

          when both are present.

          '
        schema:
          type: string
        example: gte:0,lte:10485760
      - name: flattened
        in: query
        required: false
        description: 'Force flattened/recursive search (`true`) or direct top-level

          listing (`false`). When omitted, it''s computed from whether any

          of `q`, `nodeTypes`, `recordTypes`, `origins`, `connectorIds`,

          `indexingStatus`, `createdAt`, `updatedAt`, or `size` are present —

          if any are, results are flattened automatically; otherwise only

          top-level nodes are returned.

          '
        schema:
          type: boolean
      - name: include
        in: query
        required: false
        description: 'Comma-separated list of additional response sections to include.

          Invalid values are silently ignored. Maximum 100 items.


          Valid values: `breadcrumbs`, `counts`, `availableFilters`, `permissions`

          '
        schema:
          type: string
        example: availableFilters,counts
      responses:
        '200':
          description: 'Paginated list of root hub nodes (connector apps and Collections).

            HTTP 200 returns `success: true` and `error: null`. Field-level detail

            and required keys are defined on `KnowledgeHubNodesResponse`.


            Use `include` for optional sections: `availableFilters`, `counts`,

            `permissions` — each stays JSON `null` when not asked for.

            `breadcrumbs` stays `null` at this route (no parent in the path),

            even if `include` lists `breadcrumbs`; use the child route for trails.

            `id`, `currentNode`, and `parentNode` are `null` here.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeHubNodesResponse'
              examples:
                root_apps:
                  summary: Root-level apps with availableFilters included
                  value:
                    success: true
                    error: null
                    id: null
                    currentNode: null
                    parentNode: null
                    items:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: My Knowledge Base
                      nodeType: app
                      parentId: null
                      origin: UPLOAD
                      connector: null
                      recordType: null
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1710000000000
                      sizeInBytes: null
                      mimeType: null
                      extension: null
                      webUrl: /app/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: workspace
                      isInternal: false
                      isPlaceholder: false
                    - id: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                      name: Google Drive
                      nodeType: app
                      parentId: null
                      origin: CONNECTOR
                      connector: drive
                      recordType: null
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1709000000000
                      sizeInBytes: null
                      mimeType: null
                      extension: null
                      webUrl: /app/f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: null
                      isInternal: false
                      isPlaceholder: false
                    pagination:
                      page: 1
                      limit: 20
                      totalItems: 2
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
                    filters:
                      applied:
                        q: null
                        nodeTypes: null
                        recordTypes: null
                        origins: null
                        connectorIds: null
                        indexingStatus: null
                        createdAt: null
                        updatedAt: null
                        size: null
                        sortBy: updatedAt
                        sortOrder: desc
                      available:
                        nodeTypes:
                        - id: app
                          label: Apps
                        - id: recordGroup
                          label: Record Groups
                        recordTypes: []
                        origins:
                        - id: COLLECTION
                          label: Collection
                        - id: CONNECTOR
                          label: Connector
                        connectors:
                        - id: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                          label: Google Drive
                          connectorType: drive
                        indexingStatus: []
                        sortBy:
                        - id: name
                          label: Name
                        - id: updatedAt
                          label: Updated
                        sortOrder:
                        - id: asc
                          label: Ascending
                        - id: desc
                          label: Descending
                    breadcrumbs: null
                    counts: null
                    permissions: null
        '400':
          description: 'Invalid request parameters. The backend''s validation message is

            returned verbatim in `error.message`. See the examples below for

            the common triggers.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_BAD_REQUEST
                        example: HTTP_BAD_REQUEST
                      message:
                        type: string
                        example: Search query must be at least 2 characters
              examples:
                query_too_short:
                  summary: Search query shorter than 2 characters
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: Search query must be at least 2 characters
                comma_list_too_long:
                  summary: Comma-separated parameter exceeds 100 items
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Too many items in comma-separated list (max: 100, got: 142)'
                date_range_inverted:
                  summary: Date range with gte > lte
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Date range invalid: gte must be <= lte'
                size_exceeds_max:
                  summary: Size filter exceeds the 1 TB cap
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Size exceeds maximum (1TB): 2199023255552'
        '401':
          description: 'Missing or invalid authentication token.


            The bearer token was absent, expired, malformed, or could not be

            verified by the auth middleware.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_UNAUTHORIZED
                        example: HTTP_UNAUTHORIZED
                      message:
                        type: string
                        example: Invalid token
              example:
                error:
                  code: HTTP_UNAUTHORIZED
                  message: Invalid token
        '403':
          description: 'Insufficient OAuth scope.


            Only applies to OAuth tokens. The token did not carry the `kb:read`

            scope required by this endpoint. Regular (non-OAuth) JWT bearer

            tokens are not subject to scope enforcement and will not receive

            this error.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_FORBIDDEN
                        example: HTTP_FORBIDDEN
                      message:
                        type: string
                        example: 'Insufficient scope. Required: kb:read'
              example:
                error:
                  code: HTTP_FORBIDDEN
                  message: 'Insufficient scope. Required: kb:read'
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_INTERNAL_SERVER_ERROR
                        example: HTTP_INTERNAL_SERVER_ERROR
                      message:
                        type: string
                        example: An unexpected error occurred
              example:
                error:
                  code: HTTP_INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
  /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}:
    get:
      deprecated: true
      x-speakeasy-deprecation-message: Use the Knowledge Base API instead. This grouping will be removed in a future release
      tags:
      - Knowledge Hub
      summary: Get knowledge hub child nodes
      description: 'Returns the children of a specific node in the knowledge hub tree.

        Use this endpoint to drill down into Collections, connector app

        hierarchies, folders, and record groups.


        **Navigation hierarchy**


        The typical drill-down path is:

        1. Root apps (`GET /knowledgeBase/knowledge-hub/nodes`)

        2. Record groups / folders within an app (`parentType=app`)

        3. Records within a record group (`parentType=recordGroup`)

        4. Sub-records or attachments within a record (`parentType=record`)


        **Parent identification**


        - `parentType` must be one of: `app`, `recordGroup`, `folder`, `record`

        - `parentId` must be a standard UUID


        **Filtering and searching**


        All query-param filters from the root endpoint are available here and

        operate within the scope of the parent node''s subtree. When `q` is

        provided, the search spans all descendants of the parent node.


        **Response extras**


        When `include=breadcrumbs` is set, the response contains a

        `breadcrumbs` array tracing the path from the root to the current

        node. The `currentNode` and `parentNode` objects are always populated

        for non-root requests.


        **Access control**


        Requires a valid bearer token. For OAuth tokens the `kb:read` scope

        must be present; regular JWT bearer tokens pass through without scope

        enforcement.'
      operationId: getKnowledgeHubChildNodes
      x-pipeshub-sdk: true
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: parentType
        in: path
        required: true
        description: 'Type of the parent node whose children to retrieve.


          Must be one of: `app`, `recordGroup`, `folder`, `record`.

          Any other value returns a 400 error.

          '
        schema:
          type: string
          enum:
          - app
          - recordGroup
          - folder
          - record
      - name: parentId
        in: path
        required: true
        description: 'Identifier of the parent node. Must be a valid UUID

          (e.g. `f3a4b5b6-5b6c-4e85-9097-3202cfe696fc`).


          Any value that does not match this format returns a 400 error.

          '
        schema:
          type: string
          pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      - name: onlyContainers
        in: query
        required: false
        description: 'When `true`, only nodes that have children are returned (useful for

          building sidebar / tree navigation). Leaf nodes are excluded.

          '
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        required: false
        description: 'Page number (1-indexed). Combined with `limit` to paginate results.

          '
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: 'Maximum number of items to return per page.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: sortBy
        in: query
        required: false
        description: 'Field to sort results by. Omitted → default `updatedAt`.

          Unknown value → silently falls back to `name`.

          '
        schema:
          type: string
          enum:
          - name
          - createdAt
          - updatedAt
          - size
          - type
          default: updatedAt
      - name: sortOrder
        in: query
        required: false
        description: 'Sort direction. Omitted → default `desc`.

          Unknown value → silently falls back to `asc`.

          '
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: q
        in: query
        required: false
        description: 'Full-text search query. Must be between 2 and 500 characters

          (inclusive). When provided, the endpoint searches across all

          descendants of the parent node.

          '
        schema:
          type: string
          minLength: 2
          maxLength: 500
        example: quarterly report
      - name: nodeTypes
        in: query
        required: false
        description: 'Comma-separated list of node types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `folder`, `app`, `recordGroup`, `record`

          '
        schema:
          type: string
        example: recordGroup
      - name: recordTypes
        in: query
        required: false
        description: 'Comma-separated list of record types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `FILE`, `DRIVE`, `WEBPAGE`, `DATABASE`, `DATASOURCE`,

          `MESSAGE`, `MAIL`, `GROUP_MAIL`, `TICKET`, `COMMENT`,

          `INLINE_COMMENT`, `CONFLUENCE_PAGE`, `CONFLUENCE_BLOGPOST`,

          `SHAREPOINT_PAGE`, `SHAREPOINT_LIST`, `SHAREPOINT_LIST_ITEM`,

          `SHAREPOINT_DOCUMENT_LIBRARY`, `LINK`, `PROJECT`, `PULL_REQUEST`,

          `MEETING`, `PRODUCT`, `DEAL`, `CASE`, `TASK`, `ARTIFACT`,

          `CODE_FILE`, `SQL_TABLE`, `SQL_VIEW`, `OTHERS`

          '
        schema:
          type: string
        example: FILE,CONFLUENCE_PAGE
      - name: origins
        in: query
        required: false
        description: 'Comma-separated list of origin types to include. Invalid values are

          silently ignored. Maximum 100 items.


          Valid values: `COLLECTION`, `CONNECTOR`

          '
        schema:
          type: string
        example: CONNECTOR
      - name: connectorIds
        in: query
        required: false
        description: 'Comma-separated list of connector instance IDs (UUIDs) to filter by.

          Maximum 100 items. No enum validation — any string is accepted, but

          non-existent IDs simply yield zero results.

          '
        schema:
          type: string
        example: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
      - name: indexingStatus
        in: query
        required: false
        description: 'Comma-separated list of indexing statuses to include. Invalid values

          are silently ignored. Maximum 100 items.


          Valid values: `NOT_STARTED`, `PAUSED`, `IN_PROGRESS`, `COMPLETED`,

          `FAILED`, `FILE_TYPE_NOT_SUPPORTED`, `AUTO_INDEX_OFF`, `EMPTY`,

          `ENABLE_MULTIMODAL_MODELS`, `QUEUED`

          '
        schema:
          type: string
        example: COMPLETED,FAILED
      - name: createdAt
        in: query
        required: false
        description: 'Created-date range filter. Format: `gte:<epochMs>,lte:<epochMs>`.

          Both bounds are optional (you may send just `gte:...` or just

          `lte:...`). Timestamps must be in the range 0 to 9999999999999 and

          `gte` must be less than or equal to `lte` when both are present.

          '
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: updatedAt
        in: query
        required: false
        description: 'Updated-date range filter. Same format and constraints as `createdAt`.

          '
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: size
        in: query
        required: false
        description: 'File-size range filter in bytes. Format: `gte:<bytes>,lte:<bytes>`.

          Both bounds are optional. Values must be non-negative and at most

          1099511627776 (1 TB). `gte` must be less than or equal to `lte`

          when both are present.

          '
        schema:
          type: string
        example: gte:0,lte:10485760
      - name: flattened
        in: query
        required: false
        description: 'Force flattened/recursive search (`true`) or direct top-level

          listing (`false`). When omitted, it''s computed from whether any

          of `q`, `nodeTypes`, `recordTypes`, `origins`, `connectorIds`,

          `indexingStatus`, `createdAt`, `updatedAt`, or `size` are present —

          if any are, results are flattened automatically; otherwise only

          top-level nodes are returned.

          '
        schema:
          type: boolean
      - name: include
        in: query
        required: false
        description: 'Comma-separated list of additional response sections to include.

          Invalid values are silently ignored. Maximum 100 items.


          Valid values: `breadcrumbs`, `counts`, `availableFilters`, `permissions`

          '
        schema:
          type: string
        example: breadcrumbs,availableFilters
      responses:
        '200':
          description: 'Paginated children of `{parentType}/{parentId}`. HTTP 200 returns

            `success: true` and `error: null`; see `KnowledgeHubNodesResponse` for

            the full shape.


            `id` and `currentNode` reflect the parent being browsed; `parentNode`

            is set when a grandparent exists. Optional sections (`availableFilters`,

            `counts`, `permissions`, `breadcrumbs`) are JSON `null` unless listed

            in `include` and populated by the server.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeHubNodesResponse'
              examples:
                collection_record_groups:
                  summary: Record groups inside the Collection app with breadcrumbs
                  value:
                    success: true
                    error: null
                    id: c3d4e5f6-a7b8-9012-cdef-012345678901
                    currentNode:
                      id: c3d4e5f6-a7b8-9012-cdef-012345678901
                      name: My Knowledge Base
                      nodeType: app
                      subType: null
                    parentNode: null
                    items:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Engineering Docs
                      nodeType: record
                      parentId: c3d4e5f6-a7b8-9012-cdef-012345678901
                      origin: UPLOAD
                      connector: null
                      recordType: FILE
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1709500000000
                      sizeInBytes: null
                      mimeType: application/vnd.folder
                      extension: null
                      webUrl: null
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: workspace
                      isInternal: false
                      isPlaceholder: false
                    - id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      name: HR Policies
                      nodeType: record
                      parentId: c3d4e5f6-a7b8-9012-cdef-012345678901
                      origin: UPLOAD
                      connector: null
                      recordType: FILE
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700100000000
                      updatedAt: 1709400000000
                      sizeInBytes: null
                      mimeType: application/vnd.folder
                      extension: null
                      webUrl: null
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: private
                      isInternal: false
                      isPlaceholder: false
                    pagination:
                      page: 1
                      limit: 20
                      totalItems: 2
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
                    filters:
                      applied:
                        q: null
                        nodeTypes:
                        - record
                        recordTypes: null
                        origins: null
                        connectorIds: null
                        indexingStatus: null
                        createdAt: null
                        updatedAt: null
                        size: null
                        sortBy: name
                        sortOrder: asc
                      available: null
                    breadcrumbs:
                    - id: c3d4e5f6-a7b8-9012-cdef-012345678901
                      name: My Knowledge Base
                      nodeType: app
                      subType: null
                    counts: null
                    permissions: null
        '400':
          description: 'Invalid request parameters or path values. The backend''s validation

            message is returned verbatim in `error.message`. See the examples

            below for the common triggers.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_BAD_REQUEST
                        example: HTTP_BAD_REQUEST
                      message:
                        type: string
                        example: 'Invalid parent_type. Must be one of: app, recordGroup, folder, record'
              examples:
                invalid_parent_type:
                  summary: parentType outside the allowed set
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Invalid parent_type. Must be one of: app, recordGroup, folder, record'
                invalid_parent_id:
                  summary: parentId is not a valid UUID
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Invalid UUID format for parent_id: abc'
                query_too_short:
                  summary: Search query shorter than 2 characters
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: Search query must be at least 2 characters
                comma_list_too_long:
                  summary: Comma-separated parameter exceeds 100 items
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Too many items in comma-separated list (max: 100, got: 142)'
                date_range_inverted:
                  summary: Date range with gte > lte
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Date range invalid: gte must be <= lte'
        '401':
          description: 'Missing or invalid authentication token.


            The bearer token was absent, expired, malformed, or could not be

            verified by the auth middleware.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_UNAUTHORIZED
                        example: HTTP_UNAUTHORIZED
                      message:
                        type: string
                        example: Invalid token
              example:
                error:
                  code: HTTP_UNAUTHORIZED
                  message: Invalid token
        '403':
          description: 'Insufficient OAuth scope.


            Only applies to OAuth tokens. The token did not carry the `kb:read`

            scope required by this endpoint. Regular (non-OAuth) JWT bearer

            tokens are not subject to scope enforcement and will not receive

            this error.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_FORBIDDEN
                        example: HTTP_FORBIDDEN
                      message:
                        type: string
                        example: 'Insufficient scope. Required: kb:read'
              example:
                error:
                  code: HTTP_FORBIDDEN
                  message: 'Insufficient scope. Required: kb:read'
        '404':
          description: 'Parent node not found.


            The `parentId` does not correspond to an existing node of the

            specified `parentType`, or the node has been deleted.

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_NOT_FOUND
                        example: HTTP_NOT_FOUND
                      message:
                        type: string
                        example: Parent node not found
              example:
                error:
                  code: HTTP_NOT_FOUND
                  message: Parent node not found
        '500':
          description: An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_INTERNAL_SERVER_ERROR
                        example: HTTP_INTERNAL_SERVER_ERROR
                      message:
                        type: string
                        example: An unexpected error occurred
              example:
                error:
                  code: HTTP_INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
    servers:
    - url: '{instance_url}/api/v1'
      description: Base API URL
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL (without /api/v1)
    - url: '{instance_url}'
      description: Root URL (used for MCP endpoints mounted at /mcp)
      variables:
        instance_url:
          default: https://app.pipeshub.com
          description: Base server URL
components:
  schemas:
    DateRangeFilter:
      type: object
      description: Date range filter with optional inclusive bounds (epoch ms).
      properties:
        gte:
          type:
          - integer
          - 'null'
          description: Greater-than-or-equal bound (epoch ms).
        lte:
          type:
          - integer
          - 'null'
          description: Less-than-or-equal bound (epoch ms).
    SizeRangeFilter:
      type: object
      description: Size range filter with optional inclusive bounds (bytes).
      properties:
        gte:
          type:
          - integer
          - 'null'
          description: Greater-than-or-equal bound (bytes).
        lte:
          type:
          - integer
          - 'null'
          description: Less-than-or-equal bound (bytes).
    FilterOption:
      type: object
      description: A single filter option for knowledge hub filters.
      required:
      - id
      - label
      properties:
        id:
          type: string
          description: Filter ID value to send in requests.
        label:
          type: string
          description: Display label for the filter.
        type:
          type:
          - string
          - 'null'
          description: Additional type information (currently unused, may be null).
        connectorType:
          type:
          - string
          - 'null'
          description: Connector type/name. Set only for entries in the `connectors` list.
    KnowledgeHubNodesResponse:
      type: object
      description: 'Response body for the Knowledge Hub nodes API. The deployed service

        serialises optional values as JSON `null` and always includes the keys

        listed in `required` (Swagger / clients will see stable shapes, not

        omitted properties).

        '
      required:
      - success
      - error
      - id
      - currentNode
      - parentNode
      - items
      - pagination
      - filters
      - breadcrumbs
      - counts
      - permissions
      properties:
        success:
          type: boolean
          enum:
          - true
          description: Always `true` on HTTP 200. Failures use 4xx/5xx error envelopes, not this body shape.
        error:
          type:
          - string
          - 'null'
          description: Always `null` on HTTP 200.
        id:
          type:
          - string
          - 'null'
          description: Current parent node ID when browsing children; `null` at root.
        currentNode:
          type:
          - object
          - 'null'
          description: Node being browsed when `parentId` is in the path; `null` at root.
          required:
          - id
          - name
          - nodeType
          properties:
            id:
              type: string
            name:
              type: string
            nodeType:
              type: string
              description: One of `app`, `recordGroup`, `folder`, `record`.
            subType:
              type:
              - string
              - 'null'
              description: Connector name or record type when applicable; otherwise `null`.
        parentNode:
          type:
          - object
          - 'null'
          description: Parent of `currentNode` when present; `null` when not applicable.
          required:
          - id
          - name
          - nodeType
          properties:
            id:
              type: string
            name:
              type: string
            nodeType:
              type: string
              description: One of `app`, `recordGroup`, `folder`, `record`.
            subType:
              type:
              - string
              - 'null'
        items:
          type: array
          description: Page of nodes for the current browse or search.
          items:
            $ref: '#/components/schemas/KnowledgeHubNode'
        pagination:
          type: object
          required:
          - page
          - limit
          - totalItems
          - totalPages
          - hasNext
          - hasPrev
          properties:
            page:
              type: integer
              description: Current page (1-indexed).
            limit:
              type: integer
              description: Page size.
            totalItems:
              type: integer
            totalPages:
              type: integer
            hasNext:
              type: boolean
            hasPrev:
              type: boolean
        filters:
          type: object
          required:
          - applied
          - available
          properties:
            applied:
              type: object
              description: Echo of applied filters; unused slots are JSON `null`.
              required:
              - q
              - nodeTypes
              - recordTypes
              - origins
              - connectorIds
              - indexingStatus
              - createdAt
              - updatedAt
              - size
              - sortBy
              - sortOrder
              properties:
                q:
                  type:
                  - string
                  - 'null'
                nodeTypes:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                recordTypes:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                origins:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                connectorIds:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                indexingStatus:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                createdAt:
                  allOf:
                  - $ref: '#/components/schemas/DateRangeFilter'
                updatedAt:
                  allOf:
                  - $ref: '#/components/schemas/DateRangeFilter'
                size:
                  allOf:
                  - $ref: '#/components/schemas/SizeRangeFilter'
                sortBy:
                  type: string
                  description: Effective sort field after server normalisation.
                sortOrder:
                  type: string
                  description: Effective sort order after server normalisation.
            available:
              type:
              - object
              - 'null'
              description: Populated when `include=availableFilters`; otherwise `null`.
              required:
              - nodeTypes
              - recordTypes
              - origins
              - connectors
              - indexingStatus
              - sortBy
              - sortOrder
              properties:
                nodeTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                recordTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                origins:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                connectors:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                indexingStatus:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                sortBy:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                sortOrder:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
        breadcrumbs:
          type:
          - array
          - 'null'
          description: Present when `include=breadcrumbs`; otherwise `null`.
          items:
            type: object
            required:
            - id
            - name
            - nodeType
            properties:
              id:
                type: string
              name:
                type: string
              nodeType:
                type: string
                description: One of `app`, `recordGroup`, `folder`, `record`.
              subType:
                type:
                - string
                - 'null'
        counts:
          type:
          - object
          - 'null'
          description: Present when `include=counts`; otherwise `null`.
          required:
          - items
          - total
          properties:
            items:
              type: array
              items:
                type: object
                required:
                - label
                - count
                properties:
                  label:
                    type: string
                  count:
                    type: integer
            total:
              type: integer
        permissions:
          type:
          - object
          - 'null'
          description: Present when `include=permissions`; otherwise `null`.
          required:
          - role
          - canUpload
          - canCreateFolders
          - canEdit
          - canDelete
          - canManagePermissions
          properties:
            role:
              type: string
            canUpload:
              type: boolean
            canCreateFolders:
              type: boolean
            canEdit:
              type: boolean
            canDelete:
              type: boolean
            canManagePermissions:
              type: boolean
    KnowledgeHubNode:
      type: object
      description: 'One element of `items`. The live API keeps keys stable and sets

        inapplicable values to JSON `null` (not omitted).

        '
      required:
      - id
      - name
      - nodeType
      - parentId
      - origin
      - connector
      - connectorId
      - recordType
      - recordGroupType
      - indexingStatus
      - reason
      - createdAt
      - updatedAt
      - sizeInBytes
      - mimeType
      - extension
      - webUrl
      - hasChildren
      - previewRenderable
      - permission
      - sharingStatus
      - isInternal
      - isPlaceholder
      properties:
        id:
          type: string
          description: Unique identifier for the node.
        name:
          type: string
          description: Display name of the node.
        nodeType:
          type: string
          enum:
          - app
          - recordGroup
          - folder
          - record
          description: Type of the node (app, recordGroup, folder, or record).
        parentId:
          type:
          - string
          - 'null'
          description: Parent node ID, or `null` at the root browse level.
        origin:
          type: string
          enum:
          - COLLECTION
          - CONNECTOR
          description: Origin type.
        connector:
          type:
          - string
          - 'null'
          description: Connector display name / key when applicable; otherwise `null`.
        connectorId:
          type:
          - string
          - 'null'
          description: Connector instance id for records and groups that come from a connector; otherwise `null` (Collections, and app nodes).
        recordType:
          type:
          - string
          - 'null'
          description: Record type when `nodeType` is `record`; otherwise `null`.
        recordGroupType:
          type:
          - string
          - 'null'
          description: Record group type when `nodeType` is `recordGroup`; otherwise `null`.
        indexingStatus:
          type:
          - string
          - 'null'
          description: Indexing status when `nodeType` is `record`; otherwise `null`.
        reason:
          type:
          - string
          - 'null'
          description: Failure or status reason when set; otherwise `null`.
        isInternal:
          type: boolean
          description: True for internal/system nodes that do not originate from a source.
        isPlaceholder:
          type: boolean
          description: True for placeholder/stub nodes standing in for an out-of-scope ancestor (rendered read-only, no content actions; excluded from search and indexing).
        createdAt:
          type: integer
          description: Creation timestamp (epoch ms).
        updatedAt:
          type: integer
          description: Update timestamp (epoch ms).
        sizeInBytes:
          type:
          - integer
          - 'null'
          description: File size in bytes for file records; otherwise `null`.
        mimeType:
          type:
          - string
          - 'null'
        extension:
          type:
          - string
          - 'null'
        webUrl:
          type:
          - string
          - 'null'
        hasChildren:
          type: boolean
          description: Whether the node has children (sidebar / tree).
        previewRenderable:
          type:
          - boolean
          - 'null'
        permission:
          type:
          - object
          - 'null'
          description: Per-item permission when `include=permissions` is requested; otherwise `null`.
          required:
          - role
          - canEdit
          - canDelete
          properties:
            role:
              type: string
            canEdit:
              type: boolean
            canDelete:
              type: boolean
        sharingStatus:
          type:
          - string
          - 'null'
          description: 'Sharing status (e.g. `private`, `shared`, `team`, `workspace`) when

            applicable; otherwise `null`.

            '
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT Bearer token for authenticated requests.


        A personal access token (see the **Personal Access Tokens** tag) is a

        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.

        The prefix is display-only, added for secret-scanner detectability; the

        gateway strips it before verifying the token, so send it exactly as

        issued, prefix included.

        '
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Scoped JWT token for service-to-service authentication.

        Format: "Bearer {scoped_token}"

        Required scopes vary by endpoint.

        '
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authentication with fine-grained scopes.

        Supports authorization_code (with PKCE) and client_credentials flows.

        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.

        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the OAuth app creator — see **OAuth Provider** tag.

        '
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
x-refined-from:
- pipeshub-openapi.yaml
- pipeshub-openapi.yml