CortexThreadApi

relationalai.agent.cortex

CortexThreadApi(client: httpx.Client)

Client for interacting with the Snowflake Cortex Agents Threads REST API.

Provides methods for creating, retrieving, updating, listing, and deleting conversation threads used with Cortex agents. Threads enable multi-turn conversations and message history management.

Parameters

• client

  (httpx.Client) - Configured httpx.Client with authentication headers.

Methods

.create()

CortexThreadApi.create(origin_application: Optional[str] = None) -> CreateThreadResponse

Create a new conversation thread.

Establishes a new thread for multi-turn conversations with Cortex agents. The origin_application field allows grouping threads by their source application.

Parameters:

• origin_application

  (str, default: None) - Identifier for the source application (max 16 bytes). Useful for filtering and organizing threads by application.

Returns:

• CreateThreadResponse - The new thread’s metadata including its unique ID.

Raises:

• httpx.HTTPStatusError - If the request fails.

.describe()

CortexThreadApi.describe(thread_id: int) -> DescribeThreadResponse

Retrieve thread metadata and messages.

Returns complete thread information including metadata and paginated messages in descending creation order (newest first).

Parameters:

• thread_id

  (int) - Unique identifier of the thread to retrieve.

Returns:

• DescribeThreadResponse - Thread metadata and messages.

Raises:

• httpx.HTTPStatusError - If the request fails or thread doesn’t exist.

.update()

CortexThreadApi.update(thread_id: int, thread_name: Optional[str] = None) -> None

Update thread properties.

Modifies thread metadata, specifically allowing updates to the thread name. Other thread properties are immutable.

Parameters:

• thread_id

  (int) - Unique identifier of the thread to update.

• thread_name

  (str, default: None) - New name for the thread. If None, no update is performed.

Returns:

• None

Raises:

• httpx.HTTPStatusError - If the request fails or thread doesn’t exist.

.list()

CortexThreadApi.list(origin_application: Optional[str] = None) -> ListThreadsResponse

List all threads owned by the current user.

Retrieves metadata for all threads, optionally filtered by origin application. Does not include message content.

Parameters:

• origin_application

  (str, default: None) - Filter to show only threads created by a specific application.

Returns:

• ListThreadsResponse - Thread metadata objects.

Raises:

• httpx.HTTPStatusError - If the request fails.

.delete()

CortexThreadApi.delete(thread_id: int) -> None

Delete a thread and all associated messages.

Permanently removes a thread and its complete message history. This operation cannot be undone.

Parameters:

• thread_id

  (int) - Unique identifier of the thread to delete.

Returns:

• None

Raises:

• httpx.HTTPStatusError - If the request fails or thread doesn’t exist.