chats

Classes

ChatsClient

ChatsClient(client: OWUIClientBase)

Bases: ResourceBase

Client for the Chats endpoints.

Manages chat conversations, including creating, retrieving, updating, and deleting chats, as well as managing chat history, tags, and sharing.

Used by:

• Code Reference client Classes OpenWebUI Attributes chats

Source code in src/owui_client/client_base.py

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

Functions

get_chat_usage_stats

get_chat_usage_stats(
    items_per_page: Optional[int] = 50,
    page: Optional[int] = 1,
) -> ChatUsageStatsListResponse

Get chat usage statistics.

Parameters:

Name	Type	Description	Default
items_per_page	Optional[int]	Number of items per page (default 50).	50
page	Optional[int]	The page number to retrieve (default 1).	1

Returns:

Type	Description
ChatUsageStatsListResponse	ChatUsageStatsListResponse: A list of chat usage statistics.

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

async def get_chat_usage_stats(
    self,
    items_per_page: Optional[int] = 50,
    page: Optional[int] = 1,
) -> ChatUsageStatsListResponse:
    """
    Get chat usage statistics.

    Args:
        items_per_page: Number of items per page (default 50).
        page: The page number to retrieve (default 1).

    Returns:
        `ChatUsageStatsListResponse`: A list of chat usage statistics.
    """
    params = {}
    if items_per_page:
        params["items_per_page"] = items_per_page
    if page:
        params["page"] = page

    return await self._request(
        "GET",
        "/v1/chats/stats/usage",
        model=ChatUsageStatsListResponse,
        params=params,
    )

export_chat_stats

export_chat_stats(
    updated_at: Optional[int] = None,
    page: Optional[int] = 1,
) -> ChatStatsExportList

Export chat statistics.

Parameters:

Name	Type	Description	Default
updated_at	Optional[int]	Filter by updated_at timestamp.	None
page	Optional[int]	Page number for pagination.	1

Returns:

Type	Description
ChatStatsExportList	List of exported chat statistics.

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

async def export_chat_stats(
    self,
    updated_at: Optional[int] = None,
    page: Optional[int] = 1,
) -> ChatStatsExportList:
    """
    Export chat statistics.

    Args:
        updated_at: Filter by updated_at timestamp.
        page: Page number for pagination.

    Returns:
        List of exported chat statistics.
    """
    params = {}
    if updated_at is not None:
        params["updated_at"] = updated_at
    if page is not None:
        params["page"] = page

    return await self._request(
        "GET", "/v1/chats/stats/export", model=ChatStatsExportList, params=params
    )

export_single_chat_stats

export_single_chat_stats(
    chat_id: str,
) -> Optional[ChatStatsExport]

Export statistics for a single chat.

Parameters:

Name	Type	Description	Default
chat_id	str	The ID of the chat.	required

Returns:

Type	Description
Optional[ChatStatsExport]	Exported statistics for the chat.

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

async def export_single_chat_stats(
    self,
    chat_id: str,
) -> Optional[ChatStatsExport]:
    """
    Export statistics for a single chat.

    Args:
        chat_id: The ID of the chat.

    Returns:
        Exported statistics for the chat.
    """
    return await self._request(
        "GET", f"/v1/chats/stats/export/{chat_id}", model=ChatStatsExport
    )

get_list

get_list(
    page: Optional[int] = None,
    include_pinned: Optional[bool] = False,
    include_folders: Optional[bool] = False,
) -> List[ChatTitleIdResponse]

Get a list of chats for the current user.

Parameters:

Name	Type	Description	Default
page	Optional[int]	Page number for pagination. If None, returns all chats.	None
include_pinned	Optional[bool]	Whether to include pinned chats in the response.	False
include_folders	Optional[bool]	Whether to include chats that are inside folders.	False

Returns:

Type	Description
List[ChatTitleIdResponse]	List of chat titles and IDs.

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

async def get_list(
    self,
    page: Optional[int] = None,
    include_pinned: Optional[bool] = False,
    include_folders: Optional[bool] = False,
) -> List[ChatTitleIdResponse]:
    """
    Get a list of chats for the current user.

    Args:
        page: Page number for pagination. If None, returns all chats.
        include_pinned: Whether to include pinned chats in the response.
        include_folders: Whether to include chats that are inside folders.

    Returns:
        List of chat titles and IDs.
    """
    params = {}
    if page is not None:
        params["page"] = page
    if include_pinned:
        params["include_pinned"] = include_pinned
    if include_folders:
        params["include_folders"] = include_folders

    return await self._request(
        "GET", "/v1/chats/", model=ChatTitleIdResponse, params=params
    )

delete_all

delete_all() -> bool

Delete all chats for the current user.

Returns:

Type	Description
bool	True if successful.

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

async def delete_all(self) -> bool:
    """
    Delete all chats for the current user.

    Returns:
        True if successful.
    """
    return await self._request("DELETE", "/v1/chats/", model=bool)

get_user_list

get_user_list(
    user_id: str,
    page: Optional[int] = None,
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
) -> List[ChatTitleIdResponse]

Get a list of chats for a specific user (Admin only).

Parameters:

Name	Type	Description	Default
user_id	str	ID of the user to fetch chats for.	required
page	Optional[int]	Page number for pagination.	None
query	Optional[str]	Search query for filtering chats.	None
order_by	Optional[str]	Field to order by.	None
direction	Optional[str]	Sort direction ('asc' or 'desc').	None

Returns:

Type	Description
List[ChatTitleIdResponse]	List of chat titles and IDs.

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

async def get_user_list(
    self,
    user_id: str,
    page: Optional[int] = None,
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
) -> List[ChatTitleIdResponse]:
    """
    Get a list of chats for a specific user (Admin only).

    Args:
        user_id: ID of the user to fetch chats for.
        page: Page number for pagination.
        query: Search query for filtering chats.
        order_by: Field to order by.
        direction: Sort direction ('asc' or 'desc').

    Returns:
        List of chat titles and IDs.
    """
    params = {}
    if page is not None:
        params["page"] = page
    if query:
        params["query"] = query
    if order_by:
        params["order_by"] = order_by
    if direction:
        params["direction"] = direction

    return await self._request(
        "GET", f"/v1/chats/list/user/{user_id}", model=ChatTitleIdResponse, params=params
    )

create_new

create_new(form_data: ChatForm) -> Optional[ChatResponse]

Create a new chat.

Parameters:

Name	Type	Description	Default
form_data	ChatForm	The initial data for the chat.	required

Returns:

Type	Description
Optional[ChatResponse]	The created chat object.

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

async def create_new(self, form_data: ChatForm) -> Optional[ChatResponse]:
    """
    Create a new chat.

    Args:
        form_data: The initial data for the chat.

    Returns:
        The created chat object.
    """
    return await self._request(
        "POST", "/v1/chats/new", model=ChatResponse, json=form_data.model_dump(exclude_none=True)
    )

import_chats

import_chats(
    form_data: ChatsImportForm,
) -> List[ChatResponse]

Import multiple chats.

Parameters:

Name	Type	Description	Default
form_data	ChatsImportForm	The list of chats to import.	required

Returns:

Type	Description
List[ChatResponse]	List of successfully imported chat objects.

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

async def import_chats(self, form_data: ChatsImportForm) -> List[ChatResponse]:
    """
    Import multiple chats.

    Args:
        form_data: The list of chats to import.

    Returns:
        List of successfully imported chat objects.
    """
    return await self._request(
        "POST", "/v1/chats/import", model=ChatResponse, json=form_data.model_dump(exclude_none=True)
    )

search

search(
    text: str, page: Optional[int] = None
) -> List[ChatTitleIdResponse]

Search for chats.

Parameters:

Name	Type	Description	Default
text	str	The search query text.	required
page	Optional[int]	Page number for pagination.	None

Returns:

Type	Description
List[ChatTitleIdResponse]	List of chats matching the search query.

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

async def search(
    self, text: str, page: Optional[int] = None
) -> List[ChatTitleIdResponse]:
    """
    Search for chats.

    Args:
        text: The search query text.
        page: Page number for pagination.

    Returns:
        List of chats matching the search query.
    """
    params = {"text": text}
    if page is not None:
        params["page"] = page

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

get_by_folder_id

get_by_folder_id(folder_id: str) -> List[ChatResponse]

Get all chats in a specific folder.

Parameters:

Name	Type	Description	Default
folder_id	str	ID of the folder.	required

Returns:

Type	Description
List[ChatResponse]	List of full chat objects.

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

async def get_by_folder_id(self, folder_id: str) -> List[ChatResponse]:
    """
    Get all chats in a specific folder.

    Args:
        folder_id: ID of the folder.

    Returns:
        List of full chat objects.
    """
    return await self._request(
        "GET", f"/v1/chats/folder/{folder_id}", model=ChatResponse
    )

get_list_by_folder_id

get_list_by_folder_id(
    folder_id: str, page: Optional[int] = 1
) -> List[dict]

Get a paginated list of chats in a folder.

Parameters:

Name	Type	Description	Default
folder_id	str	ID of the folder.	required
page	Optional[int]	Page number for pagination.	1

Returns:

Type	Description
List[dict]	List of dictionaries containing basic chat info (id, title, updated_at).

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

async def get_list_by_folder_id(
    self, folder_id: str, page: Optional[int] = 1
) -> List[dict]:
    """
    Get a paginated list of chats in a folder.

    Args:
        folder_id: ID of the folder.
        page: Page number for pagination.

    Returns:
        List of dictionaries containing basic chat info (id, title, updated_at).
    """
    params = {}
    if page is not None:
        params["page"] = page

    return await self._request(
        "GET", f"/v1/chats/folder/{folder_id}/list", model=dict, params=params
    )

get_pinned

get_pinned() -> List[ChatTitleIdResponse]

Get all pinned chats for the current user.

Returns:

Type	Description
List[ChatTitleIdResponse]	List of pinned chats.

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

async def get_pinned(self) -> List[ChatTitleIdResponse]:
    """
    Get all pinned chats for the current user.

    Returns:
        List of pinned chats.
    """
    return await self._request("GET", "/v1/chats/pinned", model=ChatTitleIdResponse)

get_all

get_all() -> List[ChatResponse]

Get all chats for the current user.

Returns:

Type	Description
List[ChatResponse]	List of all chat objects.

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

async def get_all(self) -> List[ChatResponse]:
    """
    Get all chats for the current user.

    Returns:
        List of all chat objects.
    """
    return await self._request("GET", "/v1/chats/all", model=ChatResponse)

get_all_archived

get_all_archived() -> List[ChatResponse]

Get all archived chats for the current user.

Returns:

Type	Description
List[ChatResponse]	List of archived chat objects.

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

async def get_all_archived(self) -> List[ChatResponse]:
    """
    Get all archived chats for the current user.

    Returns:
        List of archived chat objects.
    """
    return await self._request("GET", "/v1/chats/all/archived", model=ChatResponse)

get_all_tags

get_all_tags() -> List[TagModel]

Get all tags used by the current user across all chats.

Returns:

Type	Description
List[TagModel]	List of tag objects.

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

async def get_all_tags(self) -> List[TagModel]:
    """
    Get all tags used by the current user across all chats.

    Returns:
        List of tag objects.
    """
    return await self._request("GET", "/v1/chats/all/tags", model=TagModel)

get_all_db

get_all_db() -> List[ChatResponse]

Get all chats in the database (Admin only).

Returns:

Type	Description
List[ChatResponse]	List of all chat objects for all users.

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

async def get_all_db(self) -> List[ChatResponse]:
    """
    Get all chats in the database (Admin only).

    Returns:
        List of all chat objects for all users.
    """
    return await self._request("GET", "/v1/chats/all/db", model=ChatResponse)

get_archived_list

get_archived_list(
    page: Optional[int] = None,
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
) -> List[ChatTitleIdResponse]

Get a paginated list of archived chats.

Parameters:

Name	Type	Description	Default
page	Optional[int]	Page number for pagination.	None
query	Optional[str]	Search query string.	None
order_by	Optional[str]	Field to order results by.	None
direction	Optional[str]	Sort direction ('asc' or 'desc').	None

Returns:

Type	Description
List[ChatTitleIdResponse]	List of archived chats (lightweight).

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

async def get_archived_list(
    self,
    page: Optional[int] = None,
    query: Optional[str] = None,
    order_by: Optional[str] = None,
    direction: Optional[str] = None,
) -> List[ChatTitleIdResponse]:
    """
    Get a paginated list of archived chats.

    Args:
        page: Page number for pagination.
        query: Search query string.
        order_by: Field to order results by.
        direction: Sort direction ('asc' or 'desc').

    Returns:
        List of archived chats (lightweight).
    """
    params = {}
    if page is not None:
        params["page"] = page
    if query:
        params["query"] = query
    if order_by:
        params["order_by"] = order_by
    if direction:
        params["direction"] = direction

    return await self._request(
        "GET", "/v1/chats/archived", model=ChatTitleIdResponse, params=params
    )

archive_all

archive_all() -> bool

Archive all chats for the current user.

Returns:

Type	Description
bool	True if successful.

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

async def archive_all(self) -> bool:
    """
    Archive all chats for the current user.

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

unarchive_all

unarchive_all() -> bool

Unarchive all chats for the current user.

Returns:

Type	Description
bool	True if successful.

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

async def unarchive_all(self) -> bool:
    """
    Unarchive all chats for the current user.

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

get_archived_count

get_archived_count() -> int

Get the number of archived chats for the current user.

Returns:

Type	Description
int	The count of archived chats (server response is a bare integer).

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

async def get_archived_count(self) -> int:
    """
    Get the number of archived chats for the current user.

    Returns:
        The count of archived chats (server response is a bare integer).
    """
    return await self._request("GET", "/v1/chats/archived/count", model=int)

get_shared

get_shared(share_id: str) -> Optional[ChatResponse]

Get a shared chat.

Parameters:

Name	Type	Description	Default
share_id	str	The unique identifier for the shared chat.	required

Returns:

Type	Description
Optional[ChatResponse]	The shared chat object.

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

async def get_shared(self, share_id: str) -> Optional[ChatResponse]:
    """
    Get a shared chat.

    Args:
        share_id: The unique identifier for the shared chat.

    Returns:
        The shared chat object.
    """
    return await self._request(
        "GET", f"/v1/chats/share/{share_id}", model=ChatResponse
    )

get_by_tags

get_by_tags(
    form_data: TagFilterForm,
) -> List[ChatTitleIdResponse]

Get chats filtered by tags.

Parameters:

Name	Type	Description	Default
form_data	TagFilterForm	Filter options including the tag name and pagination.	required

Returns:

Type	Description
List[ChatTitleIdResponse]	List of chats matching the tag.

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

async def get_by_tags(self, form_data: TagFilterForm) -> List[ChatTitleIdResponse]:
    """
    Get chats filtered by tags.

    Args:
        form_data: Filter options including the tag name and pagination.

    Returns:
        List of chats matching the tag.
    """
    return await self._request(
        "POST", "/v1/chats/tags", model=ChatTitleIdResponse, json=form_data.model_dump(exclude_none=True)
    )

get

get(id: str) -> Optional[ChatResponse]

Get a chat by ID.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[ChatResponse]	The chat object.

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

async def get(self, id: str) -> Optional[ChatResponse]:
    """
    Get a chat by ID.

    Args:
        id: The chat ID.

    Returns:
        The chat object.
    """
    return await self._request("GET", f"/v1/chats/{id}", model=ChatResponse)

update

update(
    id: str, form_data: ChatForm
) -> Optional[ChatResponse]

Update a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	ChatForm	The new chat data.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object.

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

async def update(self, id: str, form_data: ChatForm) -> Optional[ChatResponse]:
    """
    Update a chat.

    Args:
        id: The chat ID.
        form_data: The new chat data.

    Returns:
        The updated chat object.
    """
    return await self._request(
        "POST", f"/v1/chats/{id}", model=ChatResponse, json=form_data.model_dump(exclude_none=True)
    )

update_message

update_message(
    id: str, message_id: str, form_data: MessageForm
) -> Optional[ChatResponse]

Update a specific message content within a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
message_id	str	The message ID.	required
form_data	MessageForm	The new message content.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object.

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

async def update_message(
    self, id: str, message_id: str, form_data: MessageForm
) -> Optional[ChatResponse]:
    """
    Update a specific message content within a chat.

    Args:
        id: The chat ID.
        message_id: The message ID.
        form_data: The new message content.

    Returns:
        The updated chat object.
    """
    return await self._request(
        "POST",
        f"/v1/chats/{id}/messages/{message_id}",
        model=ChatResponse,
        json=form_data.model_dump(exclude_none=True),
    )

send_message_event

send_message_event(
    id: str, message_id: str, form_data: EventForm
) -> Optional[bool]

Send a socket event related to a message.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
message_id	str	The message ID.	required
form_data	EventForm	The event details.	required

Returns:

Type	Description
Optional[bool]	True if successful.

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

async def send_message_event(
    self, id: str, message_id: str, form_data: EventForm
) -> Optional[bool]:
    """
    Send a socket event related to a message.

    Args:
        id: The chat ID.
        message_id: The message ID.
        form_data: The event details.

    Returns:
        True if successful.
    """
    return await self._request(
        "POST",
        f"/v1/chats/{id}/messages/{message_id}/event",
        model=bool,
        json=form_data.model_dump(exclude_none=True),
    )

delete

delete(id: str) -> bool

Delete a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
bool	True if successful.

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

async def delete(self, id: str) -> bool:
    """
    Delete a chat.

    Args:
        id: The chat ID.

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

get_pinned_status

get_pinned_status(id: str) -> Optional[bool]

Get the pinned status of a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[bool]	True if pinned, False otherwise.

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

async def get_pinned_status(self, id: str) -> Optional[bool]:
    """
    Get the pinned status of a chat.

    Args:
        id: The chat ID.

    Returns:
        True if pinned, False otherwise.
    """
    return await self._request("GET", f"/v1/chats/{id}/pinned", model=bool)

pin

pin(id: str) -> Optional[ChatResponse]

Toggle the pinned status of a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object.

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

async def pin(self, id: str) -> Optional[ChatResponse]:
    """
    Toggle the pinned status of a chat.

    Args:
        id: The chat ID.

    Returns:
        The updated chat object.
    """
    return await self._request("POST", f"/v1/chats/{id}/pin", model=ChatResponse)

clone

clone(
    id: str, form_data: CloneForm
) -> Optional[ChatResponse]

Clone a chat.

Parameters:

Name	Type	Description	Default
id	str	The ID of the chat to clone.	required
form_data	CloneForm	Cloning options (e.g. new title).	required

Returns:

Type	Description
Optional[ChatResponse]	The new chat object.

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

async def clone(self, id: str, form_data: CloneForm) -> Optional[ChatResponse]:
    """
    Clone a chat.

    Args:
        id: The ID of the chat to clone.
        form_data: Cloning options (e.g. new title).

    Returns:
        The new chat object.
    """
    return await self._request(
        "POST", f"/v1/chats/{id}/clone", model=ChatResponse, json=form_data.model_dump(exclude_none=True)
    )

clone_shared

clone_shared(id: str) -> Optional[ChatResponse]

Clone a shared chat.

Parameters:

Name	Type	Description	Default
id	str	The share ID of the shared chat.	required

Returns:

Type	Description
Optional[ChatResponse]	The newly created chat object.

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

async def clone_shared(self, id: str) -> Optional[ChatResponse]:
    """
    Clone a shared chat.

    Args:
        id: The share ID of the shared chat.

    Returns:
        The newly created chat object.
    """
    return await self._request("POST", f"/v1/chats/{id}/clone/shared", model=ChatResponse)

compact

compact(
    id: str, form_data: Optional[CompactChatForm] = None
) -> dict

Compact a chat's context by summarizing its older messages.

Triggers context compaction on the chat's current branch: the backend summarizes earlier messages so they can be dropped from the active context window while a contextSummary is kept on the checkpoint message. When form_data.model is omitted, the backend infers the model from the chat's last assistant message, then from chat.models.

Compaction only runs when enabled via config (chat.context_compaction.enable, disabled by default). When disabled the backend returns a result with compacted False without invoking a model; when enabled it calls the task model to produce the summary.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	Optional[CompactChatForm]	Optional CompactChatForm carrying an explicit model id.	None

Returns:

Type	Description
dict	An outcome dict. Keys vary by case:
dict	ok (bool): always True on success.
dict	compacted (bool): whether messages were actually summarized.
dict	reason (str): present when not compacted; one of 'disabled', 'empty', or 'too_short'.
dict	dropped_messages (int): present when compacted; count summarized out of the active context.
dict	kept_messages (int): present when compacted; count retained.
dict	summary_chars (int): present when compacted; length of the generated summary.

Raises:

Type	Description
HTTPStatusError	401 if the chat does not exist or is not owned by the caller; 409 if a generation task is still active for the chat; 400 if no model can be resolved for compaction.

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

async def compact(
    self, id: str, form_data: Optional[CompactChatForm] = None
) -> dict:
    """
    Compact a chat's context by summarizing its older messages.

    Triggers context compaction on the chat's current branch: the backend
    summarizes earlier messages so they can be dropped from the active
    context window while a `contextSummary` is kept on the checkpoint
    message. When `form_data.model` is omitted, the backend infers the model
    from the chat's last assistant message, then from `chat.models`.

    Compaction only runs when enabled via config
    (`chat.context_compaction.enable`, disabled by default). When disabled
    the backend returns a result with `compacted` False without invoking a
    model; when enabled it calls the task model to produce the summary.

    Args:
        id: The chat ID.
        form_data: Optional `CompactChatForm` carrying an explicit model id.

    Returns:
        An outcome dict. Keys vary by case:
        - `ok` (bool): always True on success.
        - `compacted` (bool): whether messages were actually summarized.
        - `reason` (str): present when not compacted; one of 'disabled', 'empty', or 'too_short'.
        - `dropped_messages` (int): present when compacted; count summarized out of the active context.
        - `kept_messages` (int): present when compacted; count retained.
        - `summary_chars` (int): present when compacted; length of the generated summary.

    Raises:
        HTTPStatusError: 401 if the chat does not exist or is not owned by
            the caller; 409 if a generation task is still active for the
            chat; 400 if no model can be resolved for compaction.
    """
    json_body = form_data.model_dump(exclude_none=True) if form_data else None
    return await self._request(
        "POST", f"/v1/chats/{id}/compact", model=dict, json=json_body
    )

archive

archive(id: str) -> Optional[ChatResponse]

Toggle the archived status of a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object.

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

async def archive(self, id: str) -> Optional[ChatResponse]:
    """
    Toggle the archived status of a chat.

    Args:
        id: The chat ID.

    Returns:
        The updated chat object.
    """
    return await self._request("POST", f"/v1/chats/{id}/archive", model=ChatResponse)

share

share(id: str) -> Optional[ChatResponse]

Share a chat.

Generates or updates the share ID for the chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object containing the share_id.

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

async def share(self, id: str) -> Optional[ChatResponse]:
    """
    Share a chat.

    Generates or updates the share ID for the chat.

    Args:
        id: The chat ID.

    Returns:
        The updated chat object containing the share_id.
    """
    return await self._request("POST", f"/v1/chats/{id}/share", model=ChatResponse)

delete_shared

delete_shared(id: str) -> Optional[bool]

Unshare a chat (delete the shared link).

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[bool]	True if successful.

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

async def delete_shared(self, id: str) -> Optional[bool]:
    """
    Unshare a chat (delete the shared link).

    Args:
        id: The chat ID.

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

unshare_all

unshare_all() -> bool

Stop sharing every chat owned by the current user.

Removes all shared snapshots, clears each chat's share_id, and deletes any shared_chat access grants in a single action.

Returns:

Type	Description
bool	True if the shared chats were removed successfully.

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

async def unshare_all(self) -> bool:
    """
    Stop sharing every chat owned by the current user.

    Removes all shared snapshots, clears each chat's `share_id`, and deletes
    any `shared_chat` access grants in a single action.

    Returns:
        True if the shared chats were removed successfully.
    """
    return await self._request("DELETE", "/v1/chats/share/all", model=bool)

update_shared_chat_access

update_shared_chat_access(
    id: str, form_data: ChatAccessGrantsForm
) -> Optional[ChatResponse]

Update access grants for a shared chat.

Sets the list of access grants controlling who can view or edit a shared chat. The server filters the requested grants against the calling user's permissions (e.g. sharing.public_chats).

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	ChatAccessGrantsForm	Access grants to apply. Each entry specifies a principal type/id and permission level.	required

Returns:

Type	Description
Optional[ChatResponse]	The chat as a ChatResponse, or None if not found.

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

async def update_shared_chat_access(
    self, id: str, form_data: ChatAccessGrantsForm
) -> Optional[ChatResponse]:
    """Update access grants for a shared chat.

    Sets the list of access grants controlling who can view or edit a
    shared chat. The server filters the requested grants against the
    calling user's permissions (e.g. `sharing.public_chats`).

    Args:
        id: The chat ID.
        form_data: Access grants to apply. Each entry specifies a
            principal type/id and permission level.

    Returns:
        The chat as a `ChatResponse`, or None if not found.
    """
    return await self._request(
        "POST",
        f"/v1/chats/shared/{id}/access/update",
        model=ChatResponse,
        json=form_data.model_dump(exclude_none=True),
    )

get_shared_chat_access

get_shared_chat_access(id: str) -> list[dict]

Get access grants for a shared chat.

Returns the current list of access grant entries for a shared chat. Each entry contains id, principal_type, principal_id, and permission.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
list[dict]	List of access grant dicts.

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

async def get_shared_chat_access(self, id: str) -> list[dict]:
    """Get access grants for a shared chat.

    Returns the current list of access grant entries for a shared chat.
    Each entry contains `id`, `principal_type`, `principal_id`, and
    `permission`.

    Args:
        id: The chat ID.

    Returns:
        List of access grant dicts.
    """
    return await self._request(
        "GET",
        f"/v1/chats/shared/{id}/access",
    )

update_folder

update_folder(
    id: str, form_data: ChatFolderIdForm
) -> Optional[ChatResponse]

Move a chat to a folder.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	ChatFolderIdForm	The target folder ID.	required

Returns:

Type	Description
Optional[ChatResponse]	The updated chat object.

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

async def update_folder(
    self, id: str, form_data: ChatFolderIdForm
) -> Optional[ChatResponse]:
    """
    Move a chat to a folder.

    Args:
        id: The chat ID.
        form_data: The target folder ID.

    Returns:
        The updated chat object.
    """
    return await self._request(
        "POST", f"/v1/chats/{id}/folder", model=ChatResponse, json=form_data.model_dump(exclude_none=True)
    )

get_tags

get_tags(id: str) -> List[TagModel]

Get tags for a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
List[TagModel]	List of tags associated with the chat.

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

async def get_tags(self, id: str) -> List[TagModel]:
    """
    Get tags for a chat.

    Args:
        id: The chat ID.

    Returns:
        List of tags associated with the chat.
    """
    return await self._request("GET", f"/v1/chats/{id}/tags", model=TagModel)

add_tag

add_tag(id: str, form_data: TagForm) -> List[TagModel]

Add a tag to a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	TagForm	The tag to add.	required

Returns:

Type	Description
List[TagModel]	Updated list of tags for the chat.

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

async def add_tag(self, id: str, form_data: TagForm) -> List[TagModel]:
    """
    Add a tag to a chat.

    Args:
        id: The chat ID.
        form_data: The tag to add.

    Returns:
        Updated list of tags for the chat.
    """
    return await self._request(
        "POST", f"/v1/chats/{id}/tags", model=TagModel, json=form_data.model_dump(exclude_none=True)
    )

delete_tag

delete_tag(id: str, form_data: TagForm) -> List[TagModel]

Remove a tag from a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required
form_data	TagForm	The tag to remove.	required

Returns:

Type	Description
List[TagModel]	Updated list of tags for the chat.

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

async def delete_tag(self, id: str, form_data: TagForm) -> List[TagModel]:
    """
    Remove a tag from a chat.

    Args:
        id: The chat ID.
        form_data: The tag to remove.

    Returns:
        Updated list of tags for the chat.
    """
    return await self._request(
        "DELETE", f"/v1/chats/{id}/tags", model=TagModel, json=form_data.model_dump(exclude_none=True)
    )

delete_all_tags

delete_all_tags(id: str) -> Optional[bool]

Remove all tags from a chat.

Parameters:

Name	Type	Description	Default
id	str	The chat ID.	required

Returns:

Type	Description
Optional[bool]	True if successful.

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

async def delete_all_tags(self, id: str) -> Optional[bool]:
    """
    Remove all tags from a chat.

    Args:
        id: The chat ID.

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

chat_completion

chat_completion(
    form_data: Union[ChatCompletionForm, dict],
) -> Union[ChatCompletionResponse, dict]

Generate a chat completion.

This endpoint provides OpenAI-compatible chat completion functionality with Open WebUI-specific features like chat management, file attachments, tools, and async processing. The response format depends on whether a session_id is provided in the request.

Parameters:

Name	Type	Description	Default
form_data	Union[ChatCompletionForm, dict]	The chat completion request containing messages, model ID, and optional parameters like chat_id, session_id, files, tools, etc. Can be a ChatCompletionForm or a dict.	required

Returns:

Type	Description
Union[ChatCompletionResponse, dict]	If session_id is provided: Returns a dict with status and task_id
Union[ChatCompletionResponse, dict]	for async processing. The task can be queried for completion status.
Union[ChatCompletionResponse, dict]	If session_id is not provided: Returns the completion response directly,
Union[ChatCompletionResponse, dict]	which may be a streaming response or a complete response object depending
Union[ChatCompletionResponse, dict]	on the stream parameter.

Notes

• When session_id is provided, the request is processed asynchronously and returns immediately with a task_id.
• When chat_id is provided, the completion is associated with an existing chat and the message is stored in the chat history.
• The endpoint supports OpenAI-compatible parameters like temperature, max_tokens, top_p, etc., which are passed through to the model.
• File attachments, tools, and retrieval filters can be included for enhanced functionality.

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

async def chat_completion(
    self, form_data: Union[ChatCompletionForm, dict]
) -> Union[ChatCompletionResponse, dict]:
    """
    Generate a chat completion.

    This endpoint provides OpenAI-compatible chat completion functionality with
    Open WebUI-specific features like chat management, file attachments, tools,
    and async processing. The response format depends on whether a session_id
    is provided in the request.

    Args:
        form_data: The chat completion request containing messages, model ID,
            and optional parameters like chat_id, session_id, files, tools, etc.
            Can be a `ChatCompletionForm` or a dict.

    Returns:
        If session_id is provided: Returns a dict with `status` and `task_id`
        for async processing. The task can be queried for completion status.

        If session_id is not provided: Returns the completion response directly,
        which may be a streaming response or a complete response object depending
        on the `stream` parameter.

    Notes:
        - When `session_id` is provided, the request is processed asynchronously
          and returns immediately with a task_id.
        - When `chat_id` is provided, the completion is associated with an existing
          chat and the message is stored in the chat history.
        - The endpoint supports OpenAI-compatible parameters like temperature,
          max_tokens, top_p, etc., which are passed through to the model.
        - File attachments, tools, and retrieval filters can be included for
          enhanced functionality.
    """
    # Convert ChatCompletionForm to dict if needed
    if isinstance(form_data, ChatCompletionForm):
        json_data = form_data.model_dump(exclude_none=True)
    else:
        json_data = {k: v for k, v in form_data.items() if v is not None}

    # Backend get_event_emitter crashes when chat_id is None in metadata.
    # Provide a local: prefixed ID so the backend treats this as a temp chat.
    if 'chat_id' not in json_data:
        chat_id = f'local:api-{uuid4()}'
        json_data['chat_id'] = chat_id
        logger.debug("No chat_id provided, generating synthetic chat_id: %s", chat_id)

    return await self._request(
        "POST",
        "/chat/completions",
        model=ChatCompletionResponse,
        json=json_data,
    )

chat_completion_api

chat_completion_api(
    form_data: Union[ChatCompletionForm, dict],
) -> Union[ChatCompletionResponse, dict]

Generate a chat completion (direct API endpoint).

This is the legacy endpoint from main.py that provides chat completion functionality.

Parameters:

Name	Type	Description	Default
form_data	Union[ChatCompletionForm, dict]	The chat completion request containing messages, model ID, and optional parameters.	required

Returns:

Type	Description
Union[ChatCompletionResponse, dict]	Chat completion response.

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

async def chat_completion_api(
    self, form_data: Union[ChatCompletionForm, dict]
) -> Union[ChatCompletionResponse, dict]:
    """
    Generate a chat completion (direct API endpoint).

    This is the legacy endpoint from main.py that provides chat completion functionality.

    Args:
        form_data: The chat completion request containing messages, model ID,
            and optional parameters.

    Returns:
        Chat completion response.
    """
    if isinstance(form_data, ChatCompletionForm):
        json_data = form_data.model_dump(exclude_none=True)
    else:
        json_data = form_data

    return await self._request(
        "POST",
        "/api/chat/completions",
        model=ChatCompletionResponse,
        json=json_data,
    )

chat_completed

chat_completed(
    form_data: Union[ChatCompletedForm, dict],
) -> Union[ChatCompletedResponse, dict]

Notify that a chat completion has been generated.

This endpoint is called after a chat completion is generated to process outlet filters that may modify the response. Outlet filters can transform the message content, add metadata, or perform other post-processing operations.

Parameters:

Name	Type	Description	Default
form_data	Union[ChatCompletedForm, dict]	The completed chat data containing model ID, message IDs, chat ID, session ID, and optional filter IDs. Can be a ChatCompletedForm or a dict.	required

Returns:

Type	Description
Union[ChatCompletedResponse, dict]	The modified form data after processing outlet filters. The response
Union[ChatCompletedResponse, dict]	structure matches the request form but may be modified by filters.

Notes

• This endpoint processes outlet filters in the order defined by the model
• Filters can modify the message content, add metadata, or perform other transformations
• The endpoint requires authentication and the user must have access to the chat
• If model_item with direct=True is provided, it bypasses the model registry

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

async def chat_completed(
    self, form_data: Union[ChatCompletedForm, dict]
) -> Union[ChatCompletedResponse, dict]:
    """
    Notify that a chat completion has been generated.

    This endpoint is called after a chat completion is generated to process
    outlet filters that may modify the response. Outlet filters can transform
    the message content, add metadata, or perform other post-processing operations.

    Args:
        form_data: The completed chat data containing model ID, message IDs,
            chat ID, session ID, and optional filter IDs. Can be a `ChatCompletedForm`
            or a dict.

    Returns:
        The modified form data after processing outlet filters. The response
        structure matches the request form but may be modified by filters.

    Notes:
        - This endpoint processes outlet filters in the order defined by the model
        - Filters can modify the message content, add metadata, or perform other transformations
        - The endpoint requires authentication and the user must have access to the chat
        - If model_item with direct=True is provided, it bypasses the model registry
    """
    # Convert ChatCompletedForm to dict if needed
    if isinstance(form_data, ChatCompletedForm):
        json_data = form_data.model_dump(exclude_none=True)
    else:
        json_data = form_data

    return await self._request(
        "POST",
        "/chat/completed",
        model=ChatCompletedResponse,
        json=json_data,
    )

chat_completed_api

chat_completed_api(
    form_data: Union[ChatCompletedForm, dict],
) -> Union[ChatCompletedResponse, dict]

Notify that a chat completion has been generated (direct API endpoint).

This is the legacy endpoint from main.py for processing outlet filters.

Parameters:

Name	Type	Description	Default
form_data	Union[ChatCompletedForm, dict]	The completed chat data.	required

Returns:

Type	Description
Union[ChatCompletedResponse, dict]	Modified form data after processing outlet filters.

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

async def chat_completed_api(
    self, form_data: Union[ChatCompletedForm, dict]
) -> Union[ChatCompletedResponse, dict]:
    """
    Notify that a chat completion has been generated (direct API endpoint).

    This is the legacy endpoint from main.py for processing outlet filters.

    Args:
        form_data: The completed chat data.

    Returns:
        Modified form data after processing outlet filters.
    """
    if isinstance(form_data, ChatCompletedForm):
        json_data = form_data.model_dump(exclude_none=True)
    else:
        json_data = form_data

    return await self._request(
        "POST",
        "/api/chat/completed",
        model=ChatCompletedResponse,
        json=json_data,
    )

chat_action

chat_action(
    action_id: str, form_data: Union[ChatActionForm, dict]
) -> Union[ChatActionResponse, dict]

Execute a chat action (POST /api/chat/actions/{action_id}).

This endpoint triggers custom actions (functions) that can process chat messages and return results. Actions are user-defined functions that can perform arbitrary operations on chat data, such as processing messages, generating content, or interacting with external services.

Parameters:

Name	Type	Description	Default
action_id	str	The ID of the action function to execute. Can include a sub-action ID separated by a dot (e.g., "action_id.sub_action_id").	required
form_data	Union[ChatActionForm, dict]	The action request containing model ID, message IDs, chat ID, session ID, and optional model configuration. Can be a ChatActionForm or a dict.	required

Returns:

Type	Description
Union[ChatActionResponse, dict]	The result of executing the action function. The response structure varies
Union[ChatActionResponse, dict]	based on the action function being executed. Actions can return any data type,
Union[ChatActionResponse, dict]	so the response may be a dict, list, string, or other types.

Notes

• Actions are user-defined functions registered in the Open WebUI system
• The action_id can include a sub-action ID separated by a dot for nested actions
• If model_item with direct=True is provided, it bypasses the model registry
• The action function receives context including the model, user, and event emitters
• Actions can emit socket events to update the UI in real-time
• Actions can return HTML responses or other rich content for display

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

async def chat_action(
    self, action_id: str, form_data: Union[ChatActionForm, dict]
) -> Union[ChatActionResponse, dict]:
    """
    Execute a chat action (POST /api/chat/actions/{action_id}).

    This endpoint triggers custom actions (functions) that can process chat messages
    and return results. Actions are user-defined functions that can perform arbitrary
    operations on chat data, such as processing messages, generating content,
    or interacting with external services.

    Args:
        action_id: The ID of the action function to execute. Can include a sub-action
            ID separated by a dot (e.g., "action_id.sub_action_id").
        form_data: The action request containing model ID, message IDs, chat ID,
            session ID, and optional model configuration. Can be a `ChatActionForm` or a dict.

    Returns:
        The result of executing the action function. The response structure varies
        based on the action function being executed. Actions can return any data type,
        so the response may be a dict, list, string, or other types.

    Notes:
        - Actions are user-defined functions registered in the Open WebUI system
        - The action_id can include a sub-action ID separated by a dot for nested actions
        - If model_item with direct=True is provided, it bypasses the model registry
        - The action function receives context including the model, user, and event emitters
        - Actions can emit socket events to update the UI in real-time
        - Actions can return HTML responses or other rich content for display
    """
    # Convert ChatActionForm to dict if needed
    if isinstance(form_data, ChatActionForm):
        json_data = form_data.model_dump(exclude_none=True)
    else:
        json_data = form_data

    return await self._request(
        "POST",
        f"/chat/actions/{action_id}",
        model=ChatActionResponse,
        json=json_data,
    )