Manage Document Collections

Create and manage knowledge base collections for RAG

POST /api/v1/knowledge/create

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Knowledge base for product guides and manuals",
    "access_grants": [
      {
        "grantee_type": "group",
        "grantee_id": "support_team",
        "permission": "read"
      }
    ]
  }'

200 - Success

{
  "id": "kb_abc123",
  "name": "Product Documentation",
  "description": "Knowledge base for product guides and manuals",
  "user_id": "user_456def",
  "data": {},
  "created_at": 1678901234,
  "updated_at": 1678901234
}

Manage knowledge base collections including creation, updating, file management, and deletion. Each knowledge base serves as a container for related documents that can be queried together.

Create Knowledge Base

POST /api/v1/knowledge/create

Create a new knowledge base collection.

Request Body

id · string

Custom identifier for the knowledge base (auto-generated if not provided)

name · string · required

Display name for the knowledge base

description · string

Description of the knowledge base content and purpose

data · object

Additional metadata to store with the knowledge base

access_grants · array

Array of access control rules. Each grant specifies permissions for users or groups.

grantee_type · string

Type of grantee: "user" or "group"

grantee_id · string

ID of the user or group

permission · string

Permission level: "read" or "write"

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/create" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Knowledge base for product guides and manuals",
    "access_grants": [
      {
        "grantee_type": "group",
        "grantee_id": "support_team",
        "permission": "read"
      }
    ]
  }'

200 - Success

{
  "id": "kb_abc123",
  "name": "Product Documentation",
  "description": "Knowledge base for product guides and manuals",
  "user_id": "user_456def",
  "data": {},
  "created_at": 1678901234,
  "updated_at": 1678901234
}

Update Knowledge Base

POST /api/v1/knowledge/{knowledge_id}/update

Request Body

Same fields as create endpoint. All fields are optional - only provided fields will be updated.

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/update" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation (Updated)",
    "description": "Updated description for the knowledge base"
  }'

Get Knowledge Base Details

GET /api/v1/knowledge/{knowledge_id}

Retrieve detailed information about a knowledge base including its files.

200 - Success

{
  "id": "kb_abc123",
  "name": "Product Documentation",
  "description": "Knowledge base for product guides and manuals",
  "user_id": "user_456def",
  "data": {},
  "files": [
    {
      "id": "file_xyz789",
      "filename": "user_guide.pdf",
      "meta": {
        "name": "user_guide.pdf",
        "size": 1234567
      }
    }
  ],
  "write_access": true,
  "created_at": 1678901234,
  "updated_at": 1678901234
}

Manage Files in Knowledge Base

List Files

GET /api/v1/knowledge/{knowledge_id}/files?page=1&query=search_term

page · integer · default: "1"

Page number for pagination

query · string

Search term to filter files by name

view_option · string

Filter by view option

order_by · string

Field to sort by (e.g., “name”, “created_at”)

direction · string

Sort direction: “asc” or “desc”

Remove File from Knowledge Base

POST /api/v1/knowledge/{knowledge_id}/file/remove

file_id · string · required

ID of the file to remove

delete_file · boolean · default: "true"

Whether to delete the file entirely or just remove from this knowledge base

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/file/remove?delete_file=false" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "file_xyz789"}'

Update File in Knowledge Base

Reprocess a file and update its embeddings:

POST /api/v1/knowledge/{knowledge_id}/file/update

file_id · string · required

ID of the file to reprocess

This will:

1. Remove existing embeddings for the file
2. Re-extract content from the file
3. Re-chunk and re-embed the content
4. Update the vector database

Reindex Knowledge Base

POST /api/v1/knowledge/reindex

Admin only. Reindex all files across all knowledge bases. Useful after changing embedding models or chunking settings.

Reset Knowledge Base

POST /api/v1/knowledge/{knowledge_id}/reset

Remove all file associations and embeddings from a knowledge base without deleting the knowledge base itself.

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/reset" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Knowledge Base

DELETE /api/v1/knowledge/{knowledge_id}/delete

Permanently delete a knowledge base and all its associations. Files are not deleted.

cURL

curl -X DELETE "https://your-domain.com/api/v1/knowledge/kb_abc123/delete" \
  -H "Authorization: Bearer YOUR_TOKEN"

Export Knowledge Base

GET /api/v1/knowledge/{knowledge_id}/export

Admin only. Export all files in a knowledge base as a ZIP archive containing .txt files with extracted content.

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="Product_Documentation.zip"

[Binary ZIP file containing text files]

Update Access Control

POST /api/v1/knowledge/{knowledge_id}/access/update

Update who can access the knowledge base.

Request Body

access_grants · array · required

Array of access control rules (replaces existing grants)

cURL

curl -X POST "https://your-domain.com/api/v1/knowledge/kb_abc123/access/update" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_grants": [
      {
        "grantee_type": "group",
        "grantee_id": "support_team",
        "permission": "read"
      },
      {
        "grantee_type": "user",
        "grantee_id": "user_xyz",
        "permission": "write"
      }
    ]
  }'

Notes

• Knowledge base IDs must be unique
• The creator automatically gets write access
• Access grants can be filtered by user permissions (e.g., sharing.public_knowledge)
• Deleting a knowledge base removes it from associated models
• Files can belong to multiple knowledge bases
• Each knowledge base has its own vector collection for embeddings
• Metadata is embedded for semantic discovery of knowledge bases