openapi: 3.2.0 info: title: Pipeshub Knowledge Base API version: 1.0.0 contact: name: API Support email: support@pipeshub.com description: 'Operations tagged Knowledge Base 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 Base description: Knowledge base management operations paths: /knowledgeBase: post: tags: - Knowledge Base summary: Create a new knowledge base description: 'Create a new knowledge base for organizing and managing documents within your organization. **Overview:** A knowledge base is a container for organizing related documents, files, and content. It provides a central location for teams to collaborate on shared information. **Features:** - Hierarchical folder structure support - Role-based access control (OWNER, WRITER, READER) - Full-text search across all records - Integration with external connectors (Google Drive, OneDrive, etc.) - Automatic content indexing for AI-powered search **Naming Rules:** - Name must be 1-255 characters - Special characters and HTML tags are sanitized - Names don''t need to be unique within organization **Creator Permissions:** The user creating the KB automatically becomes the OWNER with full administrative rights.' operationId: createKnowledgeBase x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write requestBody: required: true description: Request payload content: application/json: schema: type: object properties: kbName: type: string minLength: 1 maxLength: 255 description: Name of the knowledge base example: Product Documentation required: - kbName responses: '200': description: Knowledge base created successfully content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseCreateResponse' '400': description: '**Invalid request:** - Name too short or too long - Invalid characters in name ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - Connector service denied the request ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: User not found - Authenticated user does not exist in the graph database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error - Knowledge base creation failed in connector or database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable - Connector service is unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: tags: - Knowledge Base summary: List all knowledge bases description: 'Retrieve a paginated list of all knowledge bases accessible to the authenticated user. **Overview:** Returns knowledge bases where the user has at least READER permission. Results include the user''s role for each KB. **Filtering:** - **search:** Full-text search on KB names (max 1000 chars) - **permissions:** Filter by user''s role (comma-separated: OWNER, WRITER, READER) **Sorting Options:** - `name` — Alphabetical by KB name - `createdAtTimestamp` — By creation date - `updatedAtTimestamp` — By last modification - `userRole` — By permission level **Performance:** Uses efficient pagination with limit/offset. For large result sets, use smaller page sizes. **Query parameters:** Only `page`, `limit`, `search`, `permissions`, `sortBy`, and `sortOrder` are allowed; unknown query keys are rejected.' operationId: listKnowledgeBases x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:read parameters: - name: page in: query required: false description: Page number (1-indexed). Omitted values default to 1. schema: type: integer minimum: 1 default: 1 - name: limit in: query required: false description: Results per page (max 100). Omitted values default to 20. schema: type: integer minimum: 1 maximum: 100 default: 20 - name: search in: query required: false description: 'Search KB names (max 1000 chars). Rejected if it contains HTML/script tags, event handlers, `javascript:`, or format specifiers (validated in Zod + controller). ' schema: type: string maxLength: 1000 - name: permissions in: query required: false description: 'Comma-separated permission roles to filter by. Each token must be one of: OWNER, WRITER, READER. ' schema: type: string example: OWNER,WRITER - name: sortBy in: query required: false description: Field to sort by. schema: type: string enum: - name - createdAtTimestamp - updatedAtTimestamp - userRole default: name - name: sortOrder in: query required: false description: Sort direction. schema: type: string enum: - asc - desc default: asc responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/GetAllKnowledgeBaseResponseSchema' '400': description: '**Invalid query parameters:** - `page` not a positive integer - `limit` not between 1 and 100 - Unknown query parameter (only `page`, `limit`, `search`, `permissions`, `sortBy`, `sortOrder` allowed) - Invalid `sortBy` or `sortOrder` - Invalid `permissions` role token - `search` too long, or contains HTML/scripts/format specifiers - Connector returned a 400 error ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:read` scope - Connector service denied the request ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: User not found — authenticated user does not exist in the graph database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error — listing knowledge bases failed in connector or database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable — connector service is unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/{kbId}: get: tags: - Knowledge Base summary: Get knowledge base by ID description: 'Retrieve detailed information about a specific knowledge base. **Overview:** Returns complete KB metadata including name, timestamps, root-level folders, and the requesting user''s role. **Access Control:** User must have at least READER permission to view KB details.' operationId: getKnowledgeBase x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:read parameters: - name: kbId in: path required: true description: Knowledge base ID (non-empty string) schema: type: string minLength: 1 example: 8a095180-2989-4018-b448-70eb75fba1c7 responses: '200': description: Knowledge base retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetKnowledgeBaseById' '401': description: Unauthorized — valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:read` scope - User does not have permission to access this knowledge base - Connector service denied the request ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 'Not found. Possible reasons: - Knowledge base does not exist - Authenticated user does not exist in the graph database ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error — retrieving knowledge base failed in connector or database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable — connector service is unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: tags: - Knowledge Base summary: Update knowledge base description: 'Update a knowledge base''s name. **Required permission:** User must have one of `OWNER` or `WRITER` on the knowledge base. **Validation:** - `kbId` path parameter must be a valid UUID (`updateKBSchema`) - When provided, `kbName` must be 1–255 characters - XSS and format-specifier checks are applied to `kbName` in the gateway controller' operationId: updateKnowledgeBase x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: kbId in: path required: true description: Knowledge base ID (UUID) schema: type: string format: uuid example: 8a095180-2989-4018-b448-70eb75fba1c7 requestBody: required: true description: Fields to update. `kbName` is optional; an empty object is valid. content: application/json: schema: type: object additionalProperties: false properties: kbName: type: string minLength: 1 maxLength: 255 description: New name for the knowledge base example: Updated Documentation Hub responses: '200': description: Knowledge base updated successfully content: application/json: schema: $ref: '#/components/schemas/UpdateKnowledgeBaseById' '400': description: 'Invalid request. Possible reasons: - `kbId` is not a valid UUID (gateway `updateKBSchema`) - `kbName` is empty or longer than 255 characters - `kbName` fails XSS or format-specifier validation in the gateway controller - Invalid JSON request body at the connector (`Invalid request body`) - Connector rejected the update payload ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized — valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - User has no permission on this knowledge base - User role is insufficient (`READER`; requires `OWNER` or `WRITER`) - Connector service denied the request ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 'Not found. Possible reasons: - Knowledge base does not exist - Authenticated user does not exist in the graph database ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error — updating knowledge base failed in connector or database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable — connector service is unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: - Knowledge Base summary: Delete knowledge base description: 'Permanently delete a knowledge base and all its contents. **Required permission:** User must have `OWNER` role on the knowledge base. **What gets deleted:** - All folders within the KB - All records and their indexed content - All permission grants - Associated storage files **Warning:** This action is irreversible. Consider exporting data before deletion.' operationId: deleteKnowledgeBase x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:delete parameters: - name: kbId in: path required: true description: Knowledge base ID (non-empty string) schema: type: string minLength: 1 example: 8a095180-2989-4018-b448-70eb75fba1c7 responses: '200': description: Knowledge base deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteKnowledgeBaseById' '401': description: Unauthorized — valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:delete` scope - User has no permission on this knowledge base - User is not `OWNER` (only KB owners can delete) - Connector service denied the request ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 'Not found. Possible reasons: - Knowledge base does not exist - Authenticated user does not exist in the graph database ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error — deleting knowledge base failed in connector or database content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Service unavailable — connector service is unreachable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/record/{recordId}: get: tags: - Knowledge Base summary: Get record by ID description: 'Retrieve detailed information about a specific record. **Overview:** Returns complete record metadata including name, type, indexing status, storage information, and version history. **File conversion:** Use the optional `convertTo` parameter to request file format conversion (e.g., PDF to text). Supported conversions include PPT to PDF and PPTX to PDF.' operationId: getRecordById x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:read parameters: - name: recordId in: path required: true description: Record ID schema: type: string - name: convertTo in: query description: Optional format to convert the file to (e.g., PDF to text). Supported conversions include PPT to PDF and PPTX to PDF. schema: type: string example: txt responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/GetRecordByIdResponseSchema' '400': description: Invalid request parameters or query shape content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: OAuth token is missing the required kb:read scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Record not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Internal server error while retrieving record details. Current API behavior includes record-access lookup failures returning `HTTP_INTERNAL_SERVER_ERROR` with messages such as `Failed to check record access`, including cases where callers might otherwise expect a not-found style response. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' put: tags: - Knowledge Base summary: Update record description: 'Update a record''s name and/or file content. **Overview:** Allows updating the display name and optionally replacing the file content. Triggers re-indexing when content changes. **Required permission:** WRITER or higher **Updating file content:** Include a new file in the request to replace the existing content. The file extension must match the original. **Side effects:** - Updates `updatedAtTimestamp` - Increments version if file content changed - Triggers re-indexing for content changes' operationId: updateRecord x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: recordId in: path required: true description: Record ID schema: type: string requestBody: description: Request payload content: multipart/form-data: schema: type: object properties: recordName: type: string description: New name for the record maxLength: 255 file: type: string format: binary description: Replacement file content responses: '200': description: Record updated successfully content: application/json: schema: allOf: - type: object properties: success: type: boolean message: type: string record: $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/UpdateRecordEnrichment' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: OAuth token is missing the required kb:write scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Record not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while updating record content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: - Knowledge Base summary: Delete record description: 'Permanently delete a record from the knowledge base. **Required permission:** WRITER or higher **What gets deleted:** - Record metadata - Associated storage file - Indexed content and embeddings **Warning:** This action is irreversible.' operationId: deleteRecord x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:delete parameters: - name: recordId in: path required: true description: Record ID schema: type: string responses: '200': description: Record deleted successfully content: application/json: schema: $ref: '#/components/schemas/DeleteRecordResponseSchema' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: OAuth token is missing the required kb:delete scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Record not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while deleting record content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/stream/record/{recordId}: get: tags: - Knowledge Base summary: Stream record content description: 'Stream the binary content of a record''s file. **Overview:** Returns the raw file content with appropriate `Content-Type` and `Content-Disposition` headers for download or inline viewing. **Use cases:** - File downloads - Inline document preview - Content extraction pipelines **Format conversion:** Use the `convertTo` parameter to convert between formats (e.g. DOCX to PDF).' operationId: streamRecordBuffer x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:read parameters: - name: recordId in: path required: true description: Record ID schema: type: string - name: convertTo in: query description: Target format for conversion schema: type: string responses: '200': description: File content stream content: '*/*': schema: type: string format: binary '400': description: Invalid record ID or query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Returned either when the OAuth token is missing the required `kb:read` scope or when the authenticated user does not have access to the record. ' content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/StreamRecordErrorResponse' '404': description: Record, organization, or backing connector not found content: application/json: schema: $ref: '#/components/schemas/StreamRecordErrorResponse' '409': description: 'Conflict - the connector instance for this record is disabled. Enable it from Connector Settings and try again. ' content: application/json: schema: $ref: '#/components/schemas/StreamRecordErrorResponse' '500': description: 'Internal streaming failure, downstream conversion failure, or connector/backend error proxied by the gateway. ' content: application/json: schema: $ref: '#/components/schemas/StreamRecordErrorResponse' 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/{kbId}/folder: post: tags: - Knowledge Base summary: Create folder description: 'Create a folder in a knowledge base. Omit `folderId` to create at the KB root; pass `folderId` as a query parameter to create a nested subfolder inside an existing parent folder. **Required permission:** WRITER or higher **Folder features:** - Organize records hierarchically - Support nested subfolders (unlimited depth) - Inherit parent KB permissions **Naming rules:** - 1–255 characters - XSS protection applied - Spaces and special characters allowed - Duplicate names rejected within the same parent (`409`) **Response:** Returns `id` and `name` for the created folder.' operationId: createFolder x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: kbId in: path required: true description: Knowledge base ID schema: type: string - name: folderId in: query required: false description: Parent folder ID. Omit to create at the knowledge base root. schema: type: string requestBody: required: true description: Request payload content: application/json: schema: type: object properties: folderName: type: string minLength: 1 maxLength: 255 description: Name of the folder example: Project Documents required: - folderName responses: '200': description: Folder created successfully content: application/json: schema: $ref: '#/components/schemas/FolderCreateResponseSchema' '400': description: 'Invalid request. Possible reasons: - Missing or empty folder name - Folder name exceeds 255 characters - XSS or invalid characters in folder name ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - User lacks WRITER or higher permission on the knowledge base ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Knowledge base or parent folder not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Folder with this name already exists at the knowledge base root or within the parent folder content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while creating folder content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/{kbId}/folder/{folderId}: put: tags: - Knowledge Base summary: Update folder description: 'Rename a folder. **Required permission:** WRITER or higher' operationId: updateFolder x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: kbId in: path required: true schema: type: string - name: folderId in: path required: true schema: type: string requestBody: required: true description: Request payload content: application/json: schema: type: object properties: folderName: type: string minLength: 1 maxLength: 255 required: - folderName responses: '200': description: Folder updated successfully content: application/json: schema: $ref: '#/components/schemas/FolderUpdateResponseSchema' '400': description: 'Invalid request. Possible reasons: - Missing or empty folder name - Folder name exceeds 255 characters - XSS or invalid characters in folder name ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - User lacks WRITER or higher permission on the knowledge base ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Knowledge base or folder not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Folder with this name already exists at the knowledge base root content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while updating folder content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: tags: - Knowledge Base summary: Delete folder description: 'Delete a folder and all its contents. **Required permission:** WRITER or higher **Cascade delete:** All subfolders and records within will be permanently deleted. **Warning:** This action is irreversible.' operationId: deleteFolder x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:delete parameters: - name: kbId in: path required: true schema: type: string - name: folderId in: path required: true schema: type: string responses: '200': description: Folder deleted successfully content: application/json: schema: $ref: '#/components/schemas/FolderDeleteResponseSchema' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:delete` scope - User lacks OWNER permission on the knowledge base ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Knowledge base or folder not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/{kbId}/upload: post: tags: - Knowledge Base summary: Upload files to knowledge base or folder description: 'Upload one or more files to a knowledge base root or to a specific folder. **Overview** Batch upload multiple files in a single request. Each file becomes a new record with automatic content indexing. Omit the `folderId` query parameter to upload to the KB root; include it to upload into that folder. **Upload Limits** - **Max files per request:** 1000 - **Default max file size:** 30MB (configurable via platform settings) - Use `GET /knowledgeBase/limits` to check current limits **Supported File Types** Documents (PDF, DOCX, DOC, XLS, XLSX, PPT, PPTX, TXT, CSV, MD), Images (PNG, JPG, JPEG, SVG, WebP), Web (HTML, HTM), and Google Workspace formats. **File Metadata** Use `files_metadata` to provide additional info like file paths and last modified timestamps. **Versioning** Set `isVersioned: true` to enable version tracking for uploaded files. **Streaming response** This endpoint responds with `Content-Type: text/event-stream`. The upload and its per-file progress are a single request: the body streams a `file:succeeded` or `file:failed` event per file (including files rejected up front for size/type), followed by a final `done` summary, then closes. See the `UploadStreamSSEEvent` schema for the event/payload contract.' operationId: uploadRecords x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:upload parameters: - name: kbId in: path required: true description: Knowledge base ID schema: type: string - name: folderId in: query required: false description: Target folder ID. Omit to upload to the KB root. schema: type: string requestBody: required: true description: Request payload content: multipart/form-data: schema: type: object properties: files: type: array items: type: string format: binary description: Files to upload (max 1000) files_metadata: type: string description: JSON array with file_path and last_modified for each file example: '[{"file_path":"/docs/report.pdf","last_modified":"2024-01-15T10:30:00Z"}]' isVersioned: type: boolean default: true description: Enable version tracking recordType: type: string default: FILE description: Type of records to create required: - files responses: '200': description: 'SSE stream (`text/event-stream`) of per-file upload outcomes. The stream emits `file:succeeded` / `file:failed` per file and a final `done` summary, then closes. See `UploadStreamSSEEvent`. ' content: text/event-stream: schema: $ref: '#/components/schemas/UploadStreamSSEEvent' '400': description: Invalid request - Check file types and sizes content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permissions (requires WRITER or higher) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Knowledge base or folder not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: File size exceeds maximum allowed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many upload requests, or too many concurrent uploads for this user content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Failed to verify knowledge base or folder access content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/limits: get: tags: - Knowledge Base summary: Get knowledge base upload limits description: 'Retrieve current upload constraints for the organization. **Use case:** Call this before uploads to validate file sizes on the client side and display appropriate limits to users.' operationId: getUploadLimits x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:read responses: '200': description: Upload limits retrieved content: application/json: schema: $ref: '#/components/schemas/UploadLimitsResponseSchema' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/demo-data/status: get: tags: - Knowledge Base summary: Get your Acme Corp demo data setting description: 'Whether the bundled Acme Corp demo data reaches the caller''s answers, search and record listings. Each person chooses for themselves; until they do, the demo is on while the organization has no indexed data of its own and off once it has.' operationId: getDemoDataStatus security: - bearerAuth: [] - oauth2: - kb:read responses: '200': description: The caller's demo data setting content: application/json: schema: $ref: '#/components/schemas/DemoDataStatus' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/demo-data/preference: put: tags: - Knowledge Base summary: Show or hide the Acme Corp demo data for yourself description: 'Sets the caller''s own choice. `include: null` goes back to the default. Affects only the caller; nothing is deleted.' operationId: setDemoDataPreference security: - bearerAuth: [] - oauth2: - kb:write requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - include properties: include: type: - boolean - 'null' responses: '200': description: The caller's setting after the change content: application/json: schema: $ref: '#/components/schemas/DemoDataStatus' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/demo-data/workspace: put: tags: - Knowledge Base summary: Turn the Acme Corp demo data off, or back on, for everyone description: 'Admins only. Off hides the demo from everyone''s answers, search and records, overriding each person''s own choice, and stops the sample accounts on the demo domain from signing in. On restores both. Nothing is deleted.' operationId: setDemoDataForEveryone security: - bearerAuth: [] - oauth2: - kb:write requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - enabled properties: enabled: type: boolean responses: '200': description: The caller's demo data setting after the change content: application/json: schema: $ref: '#/components/schemas/DemoDataStatus' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Only admins can change this for everyone content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/reindex/record/{recordId}: post: tags: - Knowledge Base summary: Reindex single record description: 'Trigger reindexing for a specific record. **Overview:** Reprocesses the record''s content to update search indexes and AI embeddings. Useful after content changes or to fix indexing failures. **Depth parameter:** Controls processing depth for complex documents (`-1` for full depth, `0`–`100` for limited). **Status filters:** Optional `statusFilters` array limits reindex to records in matching indexing states (e.g. `FAILED`, `AUTO_INDEX_OFF`).' operationId: reindexRecord x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: recordId in: path required: true schema: type: string requestBody: description: Request payload content: application/json: schema: $ref: '#/components/schemas/ReindexRecordRequestBody' responses: '200': description: Reindexing triggered successfully content: application/json: schema: $ref: '#/components/schemas/reIndexRecordResponseSchema' '400': description: Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: OAuth token is missing the required kb:write scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Record not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict — the connector instance for this record is disabled. Enable it from Connector Settings and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while reindexing the record content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/reindex/record-group/{recordGroupId}: post: tags: - Knowledge Base summary: Reindex record group description: 'Trigger reindexing for all records in a folder or knowledge base. **Overview:** Batch reindex operation for entire containers. The `recordGroupId` can be a folder ID or KB ID. **Status filters:** Optional `statusFilters` limit which child records are queued (e.g. failed-only or manual-indexing).' operationId: reindexRecordGroup x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: recordGroupId in: path required: true description: Folder ID or KB ID schema: type: string requestBody: description: Request payload content: application/json: schema: $ref: '#/components/schemas/ReindexRecordGroupRequestBody' responses: '200': description: Reindexing triggered for all records in group content: application/json: schema: $ref: '#/components/schemas/ReIndexRecordGroupResponseSchema' '400': description: Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing, invalid, expired, or revoked authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: OAuth token is missing the required kb:write scope content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Record group not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - the connector instance is disabled. Enable it from Connector Settings and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while reindexing the record group content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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/{kbId}/record/{recordId}/move: put: tags: - Knowledge Base summary: Move record to another location description: 'Move a file or folder record to a different location within the same knowledge base. Set `newParentId` to a folder ID to move the record into that folder, or `null` to move it to the knowledge base root. **Required Permission:** OWNER or WRITER' operationId: moveRecord x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - kb:write parameters: - name: kbId in: path required: true schema: type: string format: uuid description: Knowledge base UUID - name: recordId in: path required: true schema: type: string minLength: 1 description: Record identifier (file or folder) requestBody: required: true description: Target location for the record content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseMoveRecordRequestBody' responses: '200': description: Record moved successfully content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseMoveRecordResponse' '400': description: 'Invalid request. Possible reasons: - Missing `newParentId` in the request body - Invalid `kbId` (must be a UUID) - Empty `recordId` - Cannot move a folder into itself - Cannot move a folder into one of its own sub-folders (circular reference) ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Valid bearer token required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden. Possible reasons: - OAuth token lacks the `kb:write` scope - User lacks OWNER or WRITER permission on the knowledge base ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: 'Not found. Possible reasons: - Knowledge base does not exist - Record does not exist in the knowledge base - Target folder does not exist in the knowledge base ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while moving record content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Connector service unavailable or connection refused content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: get: deprecated: true x-speakeasy-deprecation-message: Use the Knowledge Base API instead. This grouping will be removed in a future release tags: - Knowledge Base 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:,lte:`. 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:,lte:`. 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 Base 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:,lte:`. 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:,lte:`. 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: 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). RecordTypeEnum: type: string description: 'Type of content. Mirrors the backend `RecordType` enum (`backend/python/app/models/entities.py`); connector-sourced records may use any of the connector-specific types below. - FILE: Uploaded or synced documents (PDF, DOCX, etc.) - DRIVE: Drive/folder container (Google Drive, OneDrive, etc.) - WEBPAGE: Web pages crawled or bookmarked - DATABASE: Database object (e.g. Notion database) - DATASOURCE: Data source object - MESSAGE: Chat/messaging content (Slack, Teams) - MAIL: Email messages (Gmail, Outlook) - GROUP_MAIL: Group/shared mailbox email messages - TICKET: Support/issue tickets (Jira, ServiceNow) - COMMENT: Comments from collaboration tools - INLINE_COMMENT: Inline comments anchored to content (e.g. Confluence) - CONFLUENCE_PAGE: Confluence page - CONFLUENCE_BLOGPOST: Confluence blog post - SHAREPOINT_PAGE: SharePoint page - SHAREPOINT_LIST: SharePoint list - SHAREPOINT_LIST_ITEM: SharePoint list item - SHAREPOINT_DOCUMENT_LIBRARY: SharePoint document library - LINK: Web link / bookmark - PROJECT: Project entity (e.g. Jira project) - PULL_REQUEST: Source-control pull request - MEETING: Meeting record (e.g. Zoom) - PRODUCT: Product entity (CRM) - DEAL: Deal/opportunity entity (CRM) - CASE: Case entity (CRM/support) - TASK: Task entity - ARTIFACT: Generated/derived artifact - CODE_FILE: Source-code file - SQL_TABLE: SQL table object - SQL_VIEW: SQL view object - OTHERS: Miscellaneous content types ' enum: - 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 example: FILE ReindexRecordGroupRequestBody: type: object description: Optional body for record-group (folder/KB container) reindex. properties: depth: type: integer minimum: -1 maximum: 100 default: 0 description: Depth of records under the record group to include. force: type: boolean default: false description: Force reindex for all matched records in the group. statusFilters: type: array items: $ref: '#/components/schemas/IndexingStatusFilter' description: 'When set, only records matching these indexing statuses are reindexed. ' StreamRecordErrorResponse: type: object additionalProperties: false description: 'Error payload returned by the legacy record-stream proxy when the downstream streaming request fails after route middleware has passed. ' required: - error properties: error: type: string description: Human-readable error message from the gateway or downstream stream service ReindexRecordRequestBody: type: object description: Optional body for single-record reindex. properties: depth: type: integer minimum: -1 maximum: 100 default: 0 description: 'Child traversal depth (`0` = record only; higher values include descendants; `100` is used by clients for folder-like reindex). ' force: type: boolean default: false description: Force reindex even when the connector considers the record unchanged. statusFilters: type: array items: $ref: '#/components/schemas/IndexingStatusFilter' description: 'When set, only records whose indexing status matches one of these values are reindexed (applies to the record and its descendants per `depth`). ' UpdateRecordEnrichment: type: object description: 'Fields merged into successful record-update responses (Node gateway and Local KB connector). ' properties: timestamp: type: integer format: int64 description: Epoch milliseconds when the response was generated fileUpdated: type: boolean location: type: string enum: - kb_root - folder kb: type: object additionalProperties: true userPermission: type: string FolderCreateResponseSchema: type: object additionalProperties: false description: Response returned when a folder is created (root or nested subfolder) properties: id: type: string description: Unique folder identifier name: type: string description: Name of the folder required: - id - name GetKnowledgeBaseById: type: object additionalProperties: false description: Response returned by GET /knowledgeBase/{kbId} (getKnowledgeBase). required: - id - name - connectorId - createdAtTimestamp - updatedAtTimestamp - createdBy - userRole - folders properties: id: type: string description: Knowledge base ID name: type: string description: Knowledge base name connectorId: type: - string - 'null' description: Associated connector ID (null for manual KBs) createdAtTimestamp: type: integer format: int64 description: Creation timestamp in milliseconds updatedAtTimestamp: type: integer format: int64 description: Last update timestamp in milliseconds createdBy: type: string description: User ID of the creator userRole: type: string enum: - OWNER - WRITER - READER description: User's role in this knowledge base folders: type: array description: Root-level folders in this knowledge base items: type: object additionalProperties: false required: - id - name properties: id: type: string description: Folder ID name: type: string description: Folder name createdAtTimestamp: type: integer format: int64 description: Creation timestamp in milliseconds KnowledgeBaseMoveRecordResponse: type: object additionalProperties: false description: Response returned by PUT /knowledgeBase/{kbId}/record/{recordId}/move (moveRecord). required: - success - message properties: success: type: boolean example: true message: type: string example: Record moved successfully ErrorResponse: type: object additionalProperties: false description: 'Standard error envelope returned by all errors routed through `ErrorMiddleware`. Applies to all `BaseError` subclasses including `HttpError`, `ValidationError`, and others. The `code` field is a machine-readable string identifying the error type (e.g. `HTTP_UNAUTHORIZED`, `HTTP_NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`). ' properties: error: type: object additionalProperties: false required: - code - message properties: requestId: type: string description: 'Identifier for this request, echoed so a bug report can quote it. Absent when the request never reached the middleware that assigns one. ' code: type: string description: 'Machine-readable error code. For application errors it takes the form `HTTP_` For unhandled runtime errors (e.g. database unavailable) it is `INTERNAL_ERROR`. ' example: HTTP_BAD_REQUEST message: type: string description: Human-readable description of the error example: Admin access required metadata: type: object description: Additional context (only present in development environments) additionalProperties: true required: - error IndexingStatusFilter: type: string description: 'Indexing status used to filter which records are included in a scoped reindex (record or record-group). Omit `statusFilters` to reindex all descendants regardless of status. ' enum: - NOT_STARTED - QUEUED - IN_PROGRESS - COMPLETED - FAILED - FILE_TYPE_NOT_SUPPORTED - AUTO_INDEX_OFF - EMPTY KnowledgeBaseCreateResponse: type: object additionalProperties: false description: Response returned when a knowledge base is created properties: id: type: string description: Knowledge base ID name: type: string description: Knowledge base name createdAtTimestamp: type: integer format: int64 description: Creation timestamp in milliseconds updatedAtTimestamp: type: integer format: int64 description: Last update timestamp in milliseconds userRole: type: string enum: - OWNER - WRITER - READER description: User's role in this knowledge base required: - id - name - createdAtTimestamp - updatedAtTimestamp - userRole Record: type: object description: 'A record represents a single document, file, or content item within a knowledge base. Records can originate from file uploads or external connectors (Google Drive, OneDrive, etc.). ' properties: id: type: string description: Unique record identifier (UUID format) example: 550e8400-e29b-41d4-a716-446655440000 recordName: type: string description: Display name of the record example: Q4 Financial Report.pdf name: type: string description: Display name (alias for recordName) externalRecordId: type: string description: External storage document ID (links to Storage module) example: 507f1f77bcf86cd799439011 recordType: $ref: '#/components/schemas/RecordTypeEnum' origin: type: string enum: - UPLOAD - CONNECTOR description: 'Source of the record: - UPLOAD: Manually uploaded via API/UI - CONNECTOR: Synced from external connector ' example: UPLOAD connectorId: type: string description: ID of the connector that synced this record (null for uploads) example: conn_123456 connectorName: $ref: '#/components/schemas/ConnectorNameEnum' orgId: type: string description: Organization ID that owns this record example: org_abc123 kbId: type: string description: Knowledge base ID containing this record example: kb_xyz789 folderId: type: - string - 'null' description: Parent folder ID (null if at KB root) example: folder_456 version: type: integer description: Current version number (increments on updates) default: 0 example: 3 isLatestVersion: type: boolean description: Whether this is the latest version createdAtTimestamp: type: integer format: int64 description: Creation timestamp in milliseconds example: 1704153600000 updatedAtTimestamp: type: integer format: int64 description: Last update timestamp in milliseconds example: 1704240000000 sourceCreatedAtTimestamp: type: integer format: int64 description: Source creation timestamp (from connector) sourceLastModifiedTimestamp: type: integer format: int64 description: Source last modified timestamp (from connector) processingStartedAt: type: - integer - 'null' format: int64 description: Epoch ms when parse/index processing began for the current attempt; null when idle queuedAtTimestamp: type: - integer - 'null' format: int64 description: Epoch ms the platform last queued this record for indexing; absent until first queued. Platform-owned, unlike updatedAtTimestamp parsingStatus: type: string enum: - NOT_STARTED - IN_PROGRESS - FAILED - COMPLETED - FILE_TYPE_NOT_SUPPORTED - AUTO_INDEX_OFF - EMPTY - QUEUED description: 'Parse-phase status (ahead of indexing/extraction): - NOT_STARTED: Awaiting parsing - QUEUED: In parsing queue - IN_PROGRESS: Currently being parsed - COMPLETED: Successfully parsed - FAILED: Parsing failed - FILE_TYPE_NOT_SUPPORTED: Unsupported file format - AUTO_INDEX_OFF: Auto-indexing disabled for this record - EMPTY: File has no extractable content ' example: COMPLETED indexingStatus: type: string enum: - NOT_STARTED - PAUSED - IN_PROGRESS - COMPLETED - FAILED - FILE_TYPE_NOT_SUPPORTED - AUTO_INDEX_OFF - EMPTY - ENABLE_MULTIMODAL_MODELS - QUEUED description: 'Current indexing/processing status: - NOT_STARTED: Awaiting indexing - QUEUED: In indexing queue - IN_PROGRESS: Currently being indexed - COMPLETED: Successfully indexed and searchable - FAILED: Indexing failed (check error details) - PAUSED: Indexing paused by user - FILE_TYPE_NOT_SUPPORTED: Unsupported file format - AUTO_INDEX_OFF: Auto-indexing disabled for this record - EMPTY: File has no extractable content - ENABLE_MULTIMODAL_MODELS: Requires multimodal AI models ' example: COMPLETED isDeleted: type: boolean description: Soft delete flag default: false isArchived: type: boolean description: Archive flag for inactive records default: false webUrl: type: string format: uri description: Direct URL to access the original content example: https://drive.google.com/file/d/abc123 mimeType: type: string description: MIME type of the file content example: application/pdf sizeInBytes: type: integer format: int64 description: File size in bytes example: 1048576 extension: type: string description: File extension (without dot) example: pdf sha256Hash: type: string description: SHA-256 hash for content deduplication type: type: string description: Node type identifier example: record fileRecord: type: - object - 'null' description: File-specific metadata (present when recordType is FILE) properties: id: type: string name: type: string extension: type: string mimeType: type: string sizeInBytes: type: integer format: int64 webUrl: type: string path: type: - string - 'null' isFile: type: boolean mailRecord: type: - object - 'null' description: Email-specific metadata (present when recordType is MAIL or GROUP_MAIL) ticketRecord: type: - object - 'null' description: Ticket-specific metadata (present when recordType is TICKET) additionalProperties: true required: - recordName - recordType - origin - orgId ReIndexRecordGroupResponseSchema: type: object additionalProperties: false description: Response returned by POST /knowledgeBase/reindex/record-group/{recordGroupId}. required: - success - message - recordGroupId - depth - eventPublished properties: success: type: boolean enum: - true message: type: string recordGroupId: type: string depth: type: integer connector: type: - string - 'null' eventPublished: type: boolean FolderDeleteResponseSchema: type: object additionalProperties: false description: Response returned by DELETE /knowledgeBase/{kbId}/folder/{folderId} (deleteFolder). required: - success - message properties: success: type: boolean example: true message: type: string example: Folder deleted successfully DeleteRecordResponseSchema: type: object additionalProperties: false description: Response returned by DELETE /knowledgeBase/record/{recordId}. required: - success - message - recordId properties: success: type: boolean enum: - true message: type: string recordId: type: string connector: type: - string - 'null' timestamp: type: - integer - 'null' format: int64 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 UploadStreamSSEEvent: type: object description: "Server-Sent Event envelope for the KB streaming upload endpoint\n(`POST /knowledgeBase/{kbId}/upload`, with optional `folderId` query param).\n\nThese endpoints respond with `Content-Type: text/event-stream`: the upload\nand its per-file progress are a single request. The body streams one\nterminal event per file, then a final `done` summary, then closes. `data`\nis a JSON-encoded string whose decoded shape depends on `event`:\n\n- `file:succeeded` — see `UploadSucceededFileDetail`. The file was\n uploaded and its record created; content indexing then continues\n asynchronously.\n- `file:failed` — see `UploadFailedFileDetail`. Covers files rejected up\n front (oversize / unsupported type — these carry `reason`), files that\n failed the storage upload (`stage: \"upload\"`), and files the indexing\n service could not create (`stage: \"index\"`).\n- `done` — see `UploadDoneSummary`. Final event; the stream closes after it.\n- `error` — `{ \"message\": string }`. Emitted only on a catastrophic\n mid-stream failure (after the 200 headers were already sent), then the\n stream closes. Clients MUST treat any file without a terminal\n `file:succeeded` / `file:failed` as failed when this is received.\n\nThe stream also emits SSE comment heartbeats (`: keepalive`) roughly every\n1s during slow work; these carry no `event`/`data` and should be ignored.\nAuthentication, permission, and request-shape failures occur BEFORE the\nstream starts and are returned as ordinary 4xx JSON errors (not stream\nevents).\n" properties: event: type: string enum: - file:succeeded - file:failed - done - error data: type: string description: JSON-encoded event payload. Shape depends on `event`. ConnectorNameEnum: type: string description: 'Name of the source connector. Mirrors the values of the backend `Connectors` enum (`backend/python/app/config/constants/arangodb.py`); records store the enum value (e.g. Google Drive is `DRIVE`, SharePoint Online is `SHAREPOINT ONLINE`), not the enum member name. ' enum: - DRIVE - DRIVE WORKSPACE - GMAIL - GMAIL WORKSPACE - CALENDAR - ONEDRIVE - SHAREPOINT ONLINE - OUTLOOK - OUTLOOK PERSONAL - OUTLOOK CALENDAR - MICROSOFT TEAMS - NOTION - NOTION PERSONAL - SLACK - SLACK WORKSPACE - KB - CONFLUENCE - CONFLUENCE DATA CENTER - CONFLUENCE DATA CENTER PERSONAL - JIRA - JIRA PERSONAL - JIRA DATA CENTER - JIRA DATA CENTER PERSONAL - BOX - NEXTCLOUD - DROPBOX - DROPBOX PERSONAL - WEB - BOOKSTACK - DRUPAL WIKI - GITHUB - GITHUB TEAMS - SERVICENOW - SALESFORCE - S3 - MINIO - GCS - AZURE BLOB - AZURE FILES - LINEAR - ZAMMAD - ZOOM - GITLAB - GITLAB PERSONAL - SNOWFLAKE - POSTGRESQL - MARIADB - UNKNOWN - RSS - LOCAL_FS - CODING_SANDBOX - DATABASE_SANDBOX - IMAGE_GENERATION - ATTACHMENTS example: DRIVE GetAllKnowledgeBaseResponseSchema: type: object additionalProperties: false description: Response returned by GET /knowledgeBase (listKnowledgeBases). required: - knowledgeBases - pagination - filters properties: knowledgeBases: type: array items: type: object additionalProperties: false required: - id - name - connectorId - createdAtTimestamp - updatedAtTimestamp - createdBy - userRole - folders properties: id: type: string name: type: string connectorId: type: - string - 'null' createdAtTimestamp: type: integer format: int64 updatedAtTimestamp: type: integer format: int64 createdBy: type: string userRole: type: string enum: - OWNER - WRITER - READER folders: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string createdAtTimestamp: type: integer format: int64 path: type: string pagination: type: object additionalProperties: false required: - page - limit - totalCount - totalPages - hasNext - hasPrev properties: page: type: integer limit: type: integer totalCount: type: integer totalPages: type: integer hasNext: type: boolean hasPrev: type: boolean filters: type: object additionalProperties: false required: - applied - available properties: applied: type: object additionalProperties: false description: 'Active filters. Empty `{}` when defaults. Keys use snake_case for sort fields (backend convention in kb_service.py). ' properties: search: type: string permissions: type: array items: type: string enum: - OWNER - WRITER - READER sort_by: type: string enum: - name - createdAtTimestamp - updatedAtTimestamp - userRole sort_order: type: string enum: - asc - desc available: type: object additionalProperties: false required: - permissions - sortFields - sortOrders properties: permissions: type: array items: type: string enum: - OWNER - WRITER - READER sortFields: type: array items: type: string enum: - name - createdAtTimestamp - updatedAtTimestamp - userRole sortOrders: type: array items: type: string enum: - asc - desc DemoDataStatus: type: object required: - hasDemo - include - chosen - realData - offForEveryone - demoConnectorIds properties: hasDemo: type: boolean description: Whether the organization has the Acme Corp demo connector. include: type: boolean description: Whether the demo reaches the caller's answers, search and listings. chosen: type: - boolean - 'null' description: The caller's own choice; null while they use the default. realData: type: boolean description: Whether any source other than the demo has indexed records. offForEveryone: type: boolean description: An admin turned the demo off for the whole organization; overrides every choice. demoConnectorIds: type: array items: type: string reIndexRecordResponseSchema: type: object additionalProperties: false description: Response returned by POST /knowledgeBase/reindex/record/{recordId}. required: - success - message - eventPublished - depth properties: success: type: boolean enum: - true message: type: string recordId: type: - string - 'null' recordName: type: - string - 'null' connector: type: - string - 'null' eventPublished: type: boolean userRole: type: - string - 'null' depth: type: integer FolderUpdateResponseSchema: type: object additionalProperties: false description: Response returned by PUT /knowledgeBase/{kbId}/folder/{folderId} (updateFolder). required: - success - message properties: success: type: boolean example: true message: type: string example: Folder updated successfully UpdateKnowledgeBaseById: type: object additionalProperties: false description: Response returned by PUT /knowledgeBase/{kbId} (updateKnowledgeBase). required: - success - message properties: success: type: boolean example: true message: type: string example: Knowledge base updated successfully KnowledgeBaseMoveRecordRequestBody: type: object additionalProperties: false description: Request body for PUT /knowledgeBase/{kbId}/record/{recordId}/move (moveRecord). required: - newParentId properties: newParentId: type: - string - 'null' description: Target folder ID, or null to move the record to the knowledge base root 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`. ' 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). DeleteKnowledgeBaseById: type: object additionalProperties: false description: Response returned by DELETE /knowledgeBase/{kbId} (deleteKnowledgeBase). required: - success - message properties: success: type: boolean example: true message: type: string example: Knowledge base deleted successfully GetRecordByIdResponseSchema: type: object additionalProperties: false description: Response returned by GET /knowledgeBase/record/{recordId}. required: - record - knowledgeBase - folder - metadata - permissions properties: record: type: object additionalProperties: false required: - id - orgId - recordName - externalRecordId - connectorId - connectorName - recordType - origin - version - createdAtTimestamp - updatedAtTimestamp - sourceCreatedAtTimestamp - sourceLastModifiedTimestamp - indexingStatus - extractionStatus - isDeleted - isArchived - isVLMOcrProcessed - mimeType - sizeInBytes - webUrl - fileRecord - mailRecord - ticketRecord properties: id: type: string orgId: type: string recordName: type: string externalRecordId: type: string externalRootGroupId: type: - string - 'null' externalGroupId: type: - string - 'null' externalParentId: type: - string - 'null' externalRevisionId: type: - string - 'null' recordGroupId: type: - string - 'null' rootRecordGroupId: type: - string - 'null' description: 'Internal identifier of the top-most record group in this record''s chain. A group with no parent is its own root, so this is null only for records written before the field existed, or by connectors that do not set it. ' connectorId: type: string connectorName: $ref: '#/components/schemas/ConnectorNameEnum' recordType: $ref: '#/components/schemas/RecordTypeEnum' origin: type: string version: type: integer isLatestVersion: type: - boolean - 'null' createdAtTimestamp: type: integer format: int64 updatedAtTimestamp: type: integer format: int64 sourceCreatedAtTimestamp: type: integer format: int64 sourceLastModifiedTimestamp: type: integer format: int64 lastSyncTimestamp: type: - integer - 'null' format: int64 lastIndexTimestamp: type: integer format: int64 lastExtractionTimestamp: type: integer format: int64 processingStartedAt: type: - integer - 'null' format: int64 queuedAtTimestamp: type: - integer - 'null' format: int64 parsingStatus: type: - string - 'null' indexingStatus: type: string extractionStatus: type: string reason: type: - string - 'null' isDeleted: type: boolean isArchived: type: boolean deletedByUserId: type: - string - 'null' isDirty: type: - boolean - 'null' isVLMOcrProcessed: type: - boolean - 'null' mimeType: type: - string - 'null' sizeInBytes: type: - integer - 'null' format: int64 md5Checksum: type: - string - 'null' virtualRecordId: type: - string - 'null' summaryDocumentId: type: - string - 'null' storageDocumentId: type: - string - 'null' webUrl: type: - string - 'null' previewRenderable: type: - boolean - 'null' isShared: type: - boolean - 'null' isDependentNode: type: - boolean - 'null' parentNodeId: type: - string - 'null' hideWeburl: type: - boolean - 'null' isInternal: type: - boolean - 'null' isPlaceholder: type: - boolean - 'null' description: True for placeholder/stub records standing in for an out-of-scope ancestor (rendered read-only, no content actions; excluded from search and indexing). fileRecord: type: - object - 'null' additionalProperties: false required: - id - orgId - name - extension - isFile properties: id: type: string orgId: type: string name: type: string extension: type: string etag: type: - string - 'null' ctag: type: - string - 'null' md5Checksum: type: - string - 'null' quickXorHash: type: - string - 'null' crc32Hash: type: - string - 'null' sha1Hash: type: - string - 'null' sha256Hash: type: - string - 'null' mimeType: type: - string - 'null' sizeInBytes: type: - integer - 'null' format: int64 isFile: type: boolean webUrl: type: - string - 'null' path: type: - string - 'null' localFsRelativePath: type: - string - 'null' mailRecord: type: - object - 'null' additionalProperties: false properties: {} ticketRecord: type: - object - 'null' additionalProperties: false properties: {} knowledgeBase: type: - object - 'null' additionalProperties: false required: - id - name - orgId properties: id: type: string name: type: string orgId: type: string folder: type: - object - 'null' additionalProperties: false required: - id - name properties: id: type: string name: type: string metadata: type: object additionalProperties: false required: - languages - topics - subcategories1 - subcategories2 - subcategories3 - departments - categories properties: languages: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string topics: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string subcategories1: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string subcategories2: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string subcategories3: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string departments: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string categories: type: array items: type: object additionalProperties: false required: - id - name properties: id: type: string name: type: string permissions: type: array items: type: object additionalProperties: false required: - id - name - type - relationship - accessType properties: id: type: string name: type: string type: type: string relationship: type: string enum: - OWNER - WRITER - READER accessType: type: string UploadLimitsResponseSchema: type: object additionalProperties: false description: Upload constraints returned by GET /knowledgeBase/limits. required: - maxFilesPerRequest - maxFileSizeBytes properties: maxFilesPerRequest: type: integer minimum: 1 example: 1000 description: Maximum number of files per upload request maxFileSizeBytes: type: integer minimum: 1 example: 31457280 description: Maximum file size in bytes (default 30MB when platform settings unavailable) 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