knowledge

Classes

KnowledgeClient

KnowledgeClient(client: OWUIClientBase)

Bases: ResourceBase

Client for the Knowledge endpoints.

Used by:

• Code Reference client Classes OpenWebUI Attributes knowledge

Source code in src/owui_client/client_base.py

def __init__(self, client: OWUIClientBase):
    self._client = client

Functions

get_knowledge

get_knowledge(page: int = 1) -> KnowledgeAccessListResponse

Get knowledge bases (read access).

Parameters:

Name	Type	Description	Default
page	int	Page number (default 1).	1

Returns:

Type	Description
KnowledgeAccessListResponse	KnowledgeAccessListResponse: List of knowledge bases the user has read access to, with pagination.

Source code in src/owui_client/routers/knowledge.py

async def get_knowledge(self, page: int = 1) -> KnowledgeAccessListResponse:
    """
    Get knowledge bases (read access).

    Args:
        page: Page number (default 1).

    Returns:
        `KnowledgeAccessListResponse`: List of knowledge bases the user has read access to, with pagination.
    """
    return await self._request(
        "GET",
        "/v1/knowledge/",
        model=KnowledgeAccessListResponse,
        params={"page": page},
    )

get_knowledge_list

get_knowledge_list() -> List[KnowledgeUserResponse]

Get knowledge bases list (write access).

Returns:

Type	Description
List[KnowledgeUserResponse]	List[KnowledgeUserResponse]: List of knowledge bases the user has write access to.

Source code in src/owui_client/routers/knowledge.py

async def get_knowledge_list(self) -> List[KnowledgeUserResponse]:
    """
    Get knowledge bases list (write access).

    Returns:
        List[KnowledgeUserResponse]: List of knowledge bases the user has write access to.
    """
    return await self._request(
        "GET", "/v1/knowledge/list", model=KnowledgeUserResponse
    )

search_knowledge_bases

search_knowledge_bases(query: Optional[str] = None, view_option: Optional[str] = None, page: Optional[int] = 1) -> KnowledgeAccessListResponse

Search knowledge bases.

Parameters:

Name	Type	Description	Default
query	Optional[str]	Search query string.	None
view_option	Optional[str]	View option filter (e.g., 'created', 'shared').	None
page	Optional[int]	Page number (default 1).	1

Returns:

Type	Description
KnowledgeAccessListResponse	KnowledgeAccessListResponse: List of knowledge bases matching criteria.

Source code in src/owui_client/routers/knowledge.py

async def search_knowledge_bases(
    self,
    query: Optional[str] = None,
    view_option: Optional[str] = None,
    page: Optional[int] = 1,
) -> KnowledgeAccessListResponse:
    """
    Search knowledge bases.

    Args:
        query: Search query string.
        view_option: View option filter (e.g., 'created', 'shared').
        page: Page number (default 1).

    Returns:
        `KnowledgeAccessListResponse`: List of knowledge bases matching criteria.
    """
    params = {}
    if query:
        params["query"] = query
    if view_option:
        params["view_option"] = view_option
    if page:
        params["page"] = page

    return await self._request(
        "GET",
        "/v1/knowledge/search",
        model=KnowledgeAccessListResponse,
        params=params,
    )

search_knowledge_files

search_knowledge_files(query: Optional[str] = None, page: Optional[int] = 1) -> KnowledgeFileListResponse

Search files across all knowledge bases.

Parameters:

Name	Type	Description	Default
query	Optional[str]	Search query string.	None
page	Optional[int]	Page number (default 1).	1

Returns:

Type	Description
KnowledgeFileListResponse	KnowledgeFileListResponse: List of files matching criteria.

Source code in src/owui_client/routers/knowledge.py

async def search_knowledge_files(
    self,
    query: Optional[str] = None,
    page: Optional[int] = 1,
) -> KnowledgeFileListResponse:
    """
    Search files across all knowledge bases.

    Args:
        query: Search query string.
        page: Page number (default 1).

    Returns:
        `KnowledgeFileListResponse`: List of files matching criteria.
    """
    params = {}
    if query:
        params["query"] = query
    if page:
        params["page"] = page

    return await self._request(
        "GET",
        "/v1/knowledge/search/files",
        model=KnowledgeFileListResponse,
        params=params,
    )

create_new_knowledge

create_new_knowledge(form_data: KnowledgeForm) -> Optional[KnowledgeResponse]

Create a new knowledge base.

Requires workspace.knowledge permission. If access_control is None (public), requires sharing.public_knowledge permission. If the user lacks sharing.public_knowledge permission, access_control will default to private {}.

Parameters:

Name	Type	Description	Default
form_data	KnowledgeForm	The data for the new knowledge base.	required

Returns:

Type	Description
Optional[KnowledgeResponse]	Optional[KnowledgeResponse]: The created knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def create_new_knowledge(
    self, form_data: KnowledgeForm
) -> Optional[KnowledgeResponse]:
    """
    Create a new knowledge base.

    Requires `workspace.knowledge` permission.
    If `access_control` is `None` (public), requires `sharing.public_knowledge` permission.
    If the user lacks `sharing.public_knowledge` permission, `access_control` will default to private `{}`.

    Args:
        form_data: The data for the new knowledge base.

    Returns:
        Optional[KnowledgeResponse]: The created knowledge base.
    """
    return await self._request(
        "POST",
        "/v1/knowledge/create",
        model=KnowledgeResponse,
        json=form_data.model_dump(),
    )

get_knowledge_by_id

get_knowledge_by_id(id: str) -> Optional[KnowledgeFilesResponse]

Get a knowledge base by ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The knowledge base details including files.

Source code in src/owui_client/routers/knowledge.py

async def get_knowledge_by_id(self, id: str) -> Optional[KnowledgeFilesResponse]:
    """
    Get a knowledge base by ID.

    Args:
        id: The ID of the knowledge base.

    Returns:
        Optional[KnowledgeFilesResponse]: The knowledge base details including files.
    """
    return await self._request(
        "GET", f"/v1/knowledge/{id}", model=KnowledgeFilesResponse
    )

update_knowledge_by_id

update_knowledge_by_id(id: str, form_data: KnowledgeForm) -> Optional[KnowledgeFilesResponse]

Update a knowledge base by ID.

Requires write access to the knowledge base or admin privileges. If access_control is None (public), requires sharing.public_knowledge permission. If the user lacks sharing.public_knowledge permission, access_control will default to private {}.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
form_data	KnowledgeForm	The updated data.	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def update_knowledge_by_id(
    self, id: str, form_data: KnowledgeForm
) -> Optional[KnowledgeFilesResponse]:
    """
    Update a knowledge base by ID.

    Requires write access to the knowledge base or admin privileges.
    If `access_control` is `None` (public), requires `sharing.public_knowledge` permission.
    If the user lacks `sharing.public_knowledge` permission, `access_control` will default to private `{}`.

    Args:
        id: The ID of the knowledge base.
        form_data: The updated data.

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base.
    """
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/update",
        model=KnowledgeFilesResponse,
        json=form_data.model_dump(),
    )

update_knowledge_access

update_knowledge_access(id: str, access_grants: list[dict]) -> Optional[KnowledgeFilesResponse]

Update access grants for a knowledge base.

Requires write access to the knowledge base or admin privileges. If setting public access (principal_id='*'), requires sharing.public_knowledge permission. If the user lacks permission, public grants will be stripped.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
access_grants	list[dict]	List of access grant dictionaries. Each dict should contain: - principal_type (str): 'user' or 'group' - principal_id (str): User/group ID, or '*' for public access - permission (str): 'read' or 'write'	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base with files.

Source code in src/owui_client/routers/knowledge.py

async def update_knowledge_access(
    self, id: str, access_grants: list[dict]
) -> Optional[KnowledgeFilesResponse]:
    """
    Update access grants for a knowledge base.

    Requires write access to the knowledge base or admin privileges.
    If setting public access (principal_id='*'), requires `sharing.public_knowledge` permission.
    If the user lacks permission, public grants will be stripped.

    Args:
        id: The ID of the knowledge base.
        access_grants: List of access grant dictionaries. Each dict should contain:
            - `principal_type` (str): 'user' or 'group'
            - `principal_id` (str): User/group ID, or '*' for public access
            - `permission` (str): 'read' or 'write'

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base with files.
    """
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/access/update",
        model=KnowledgeFilesResponse,
        json={"access_grants": access_grants},
    )

delete_knowledge_by_id

delete_knowledge_by_id(id: str) -> bool

Delete a knowledge base by ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required

Returns:

Name	Type	Description
bool	bool	True if successful.

Source code in src/owui_client/routers/knowledge.py

async def delete_knowledge_by_id(self, id: str) -> bool:
    """
    Delete a knowledge base by ID.

    Args:
        id: The ID of the knowledge base.

    Returns:
        bool: True if successful.
    """
    return await self._request("DELETE", f"/v1/knowledge/{id}/delete", model=bool)

add_file_to_knowledge

add_file_to_knowledge(id: str, file_id: str) -> Optional[KnowledgeFilesResponse]

Add a file to a knowledge base.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
file_id	str	The ID of the file to add.	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def add_file_to_knowledge(
    self, id: str, file_id: str
) -> Optional[KnowledgeFilesResponse]:
    """
    Add a file to a knowledge base.

    Args:
        id: The ID of the knowledge base.
        file_id: The ID of the file to add.

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base.
    """
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/file/add",
        model=KnowledgeFilesResponse,
        json={"file_id": file_id},
    )

update_file_from_knowledge

update_file_from_knowledge(id: str, file_id: str) -> Optional[KnowledgeFilesResponse]

Update a file in a knowledge base (re-process).

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
file_id	str	The ID of the file to update.	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def update_file_from_knowledge(
    self, id: str, file_id: str
) -> Optional[KnowledgeFilesResponse]:
    """
    Update a file in a knowledge base (re-process).

    Args:
        id: The ID of the knowledge base.
        file_id: The ID of the file to update.

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base.
    """
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/file/update",
        model=KnowledgeFilesResponse,
        json={"file_id": file_id},
    )

remove_file_from_knowledge

remove_file_from_knowledge(id: str, file_id: str, delete_file: bool = True) -> Optional[KnowledgeFilesResponse]

Remove a file from a knowledge base.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
file_id	str	The ID of the file to remove.	required
delete_file	bool	Whether to delete the file from the system as well.	True

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def remove_file_from_knowledge(
    self, id: str, file_id: str, delete_file: bool = True
) -> Optional[KnowledgeFilesResponse]:
    """
    Remove a file from a knowledge base.

    Args:
        id: The ID of the knowledge base.
        file_id: The ID of the file to remove.
        delete_file: Whether to delete the file from the system as well.

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base.
    """
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/file/remove",
        model=KnowledgeFilesResponse,
        params={"delete_file": delete_file},
        json={"file_id": file_id},
    )

reset_knowledge_by_id

reset_knowledge_by_id(id: str) -> Optional[KnowledgeResponse]

Reset a knowledge base by ID (remove all files).

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required

Returns:

Type	Description
Optional[KnowledgeResponse]	Optional[KnowledgeResponse]: The reset knowledge base.

Source code in src/owui_client/routers/knowledge.py

async def reset_knowledge_by_id(self, id: str) -> Optional[KnowledgeResponse]:
    """
    Reset a knowledge base by ID (remove all files).

    Args:
        id: The ID of the knowledge base.

    Returns:
        Optional[KnowledgeResponse]: The reset knowledge base.
    """
    return await self._request(
        "POST", f"/v1/knowledge/{id}/reset", model=KnowledgeResponse
    )

reindex_knowledge_files

reindex_knowledge_files() -> bool

Reindex all knowledge files.

This is a blocking operation that reprocesses all files in all knowledge bases. Requires Admin privileges.

Returns:

Name	Type	Description
bool	bool	True if successful.

Source code in src/owui_client/routers/knowledge.py

async def reindex_knowledge_files(self) -> bool:
    """
    Reindex all knowledge files.

    This is a blocking operation that reprocesses all files in all knowledge bases.
    Requires Admin privileges.

    Returns:
        bool: True if successful.
    """
    return await self._request("POST", "/v1/knowledge/reindex", model=bool)

add_files_to_knowledge_batch

add_files_to_knowledge_batch(id: str, file_ids: List[str]) -> Optional[KnowledgeFilesResponse]

Add multiple files to a knowledge base in batch.

This process iterates through files and adds them to the vector database. Failures are collected in the response warnings field.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required
file_ids	List[str]	List of file IDs to add.	required

Returns:

Type	Description
Optional[KnowledgeFilesResponse]	Optional[KnowledgeFilesResponse]: The updated knowledge base.
Optional[KnowledgeFilesResponse]	Check warnings field for any processing errors.

Source code in src/owui_client/routers/knowledge.py

async def add_files_to_knowledge_batch(
    self, id: str, file_ids: List[str]
) -> Optional[KnowledgeFilesResponse]:
    """
    Add multiple files to a knowledge base in batch.

    This process iterates through files and adds them to the vector database.
    Failures are collected in the response `warnings` field.

    Args:
        id: The ID of the knowledge base.
        file_ids: List of file IDs to add.

    Returns:
        Optional[KnowledgeFilesResponse]: The updated knowledge base.
        Check `warnings` field for any processing errors.
    """
    data = [{"file_id": fid} for fid in file_ids]
    return await self._request(
        "POST",
        f"/v1/knowledge/{id}/files/batch/add",
        model=KnowledgeFilesResponse,
        json=data,
    )

reindex_metadata

reindex_metadata() -> dict

Reindex knowledge base metadata embeddings.

Requires Admin privileges.

Returns:

Name	Type	Description
dict	dict	Statistics about the reindexing process (total, success).

Source code in src/owui_client/routers/knowledge.py

async def reindex_metadata(self) -> dict:
    """
    Reindex knowledge base metadata embeddings.

    Requires Admin privileges.

    Returns:
        dict: Statistics about the reindexing process (total, success).
    """
    return await self._request("POST", "/v1/knowledge/metadata/reindex", model=dict)

export

export(id: str) -> bytes

Export a knowledge base as a zip file.

Requires Admin privileges.

Parameters:

Name	Type	Description	Default
id	str	The ID of the knowledge base.	required

Returns:

Name	Type	Description
bytes	bytes	The zip file content.

Source code in src/owui_client/routers/knowledge.py

async def export(self, id: str) -> bytes:
    """
    Export a knowledge base as a zip file.

    Requires Admin privileges.

    Args:
        id: The ID of the knowledge base.

    Returns:
        bytes: The zip file content.
    """
    return await self._request("GET", f"/v1/knowledge/{id}/export", model=bytes)