openapi: 3.2.0 info: title: Happyrobot Public Knowledge Bases API description: Public API endpoints for Happyrobot version: 0.1.1 servers: - url: https://platform.happyrobot.ai/api/v2 security: - bearerAuth: [] tags: - name: Knowledge Bases paths: /knowledge-bases/: get: tags: - Knowledge Bases description: List all knowledge bases for the organization. responses: '200': description: Default Response post: tags: - Knowledge Bases description: Create a new knowledge base for the organization. requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: type: string max_file_size_mb: type: integer minimum: 1 maximum: 1024 required: - name required: true responses: '201': description: Default Response content: application/json: schema: type: object properties: knowledge_base: type: object properties: id: type: string org_id: type: string name: type: string description: type: - string - 'null' max_file_size_mb: type: integer minimum: -9007199254740991 maximum: 9007199254740991 created_at: type: string updated_at: type: string required: - id - org_id - name - description - max_file_size_mb - created_at - updated_at additionalProperties: false required: - knowledge_base additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /knowledge-bases/{kbId}/files: get: tags: - Knowledge Bases description: List all files in a knowledge base. Use this endpoint to check file processing status after triggering chunking via POST /:kbId/trigger-chunking. parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: kbId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: files: type: array items: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ kb_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ file_size_in_bytes: type: integer minimum: -2147483648 maximum: 2147483647 org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ external_uri: type: string name: type: string maxLength: 256 type: type: string maxLength: 256 uploaded_by: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ last_updated: type: string format: date-time processing_status: type: - string - 'null' maxLength: 64 chunking_config: anyOf: - anyOf: - type: string - type: number - type: boolean - type: - string - 'null' enum: - null - type: object additionalProperties: {} - type: array items: {} summary: type: - string - 'null' summary_keywords: type: - array - 'null' items: type: string parsed_content: type: - string - 'null' source_url: type: - string - 'null' source_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ content_hash: type: - string - 'null' alchemist_elixir_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ created_at: type: string format: date-time uploaded_by_email: type: - string - 'null' required: - id - kb_id - file_size_in_bytes - org_id - external_uri - name - type - uploaded_by - last_updated - processing_status - chunking_config - summary - summary_keywords - parsed_content - source_url - source_id - content_hash - alchemist_elixir_id - created_at additionalProperties: false required: - files additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /knowledge-bases/{kbId}/upload-urls: post: tags: - Knowledge Bases description: Step 1 of the file upload flow. Creates file records in the database and returns presigned S3 URLs (valid for 3 minutes). Upload files directly to S3 using the returned uploadUrl for each file, then call POST /:kbId/trigger-chunking with the returned fileIds to start processing. requestBody: content: application/json: schema: type: object properties: files: type: array items: type: object properties: fileName: type: string minLength: 1 contentType: type: string minLength: 1 contentLength: type: number exclusiveMinimum: 0 required: - fileName - contentType - contentLength required: - files required: true parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: kbId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: files: type: array items: type: object properties: fileId: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ fileName: type: string uploadUrl: type: string format: uri required: - fileId - fileName - uploadUrl additionalProperties: false required: - files additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /knowledge-bases/{kbId}/trigger-chunking: post: tags: - Knowledge Bases description: Step 2 of the file upload flow. Call this endpoint after uploading files to S3 using the presigned URLs from POST /:kbId/upload-urls. Triggers embedding generation for the specified files. Files will be available in the knowledge base within 10-15 minutes. Use GET /:kbId/files to check processing status. requestBody: content: application/json: schema: type: object properties: fileIds: minItems: 1 type: array items: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - fileIds required: true parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: kbId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: message: type: string fileIds: type: array items: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - message - fileIds additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /knowledge-bases/{kbId}: delete: tags: - Knowledge Bases description: Delete a knowledge base and all associated files and chunks. This action is irreversible. parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: kbId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: message: type: string kbId: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - message - kbId additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /knowledge-bases/{kbId}/files/{fileId}: delete: tags: - Knowledge Bases description: Delete a file from a knowledge base. This removes the file from storage and deletes all associated chunks. This action is irreversible. parameters: - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: kbId required: true - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: path name: fileId required: true responses: '200': description: Default Response content: application/json: schema: type: object properties: message: type: string fileId: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - message - fileId additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '409': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Opaque