Implementation:Openai Openai node ChatKit Threads Resource

Knowledge Sources	Openai_Openai_node
Domains	SDK, ChatKit, Beta
Last Updated	2026-02-15 12:00 GMT

Overview

The ChatKit Threads resource class provides methods to retrieve, list, delete, and list items within ChatKit threads via the ChatKit beta API.

Description

The Threads class extends APIResource and exposes four methods -- retrieve, list, delete, and listItems -- that map to the /chatkit/threads REST endpoints. Each method automatically injects the OpenAI-Beta: chatkit_beta=v1 header. The resource uses ConversationCursorPage for pagination rather than the standard CursorPage.

The file defines a rich set of types to model the ChatKit thread ecosystem. The ChatKitThread interface represents a thread with status discriminated unions (active, locked, closed). Thread items are modeled as a union including ChatKitThreadUserMessageItem, ChatKitThreadAssistantMessageItem, ChatKitWidgetItem, ChatKitClientToolCall, ChatKitTask, and ChatKitTaskGroup. The assistant message items contain ChatKitResponseOutputText with annotations (file or URL references).

The file also exports session-related types such as ChatSession, ChatSessionChatKitConfiguration, ChatSessionWorkflowParam, and ChatSessionRateLimits which define configuration and lifecycle information for ChatKit sessions including automatic thread titling, file upload settings, history retention, and rate limiting.

Usage

Use this resource to interact with ChatKit threads. Access it via client.beta.chatkit.threads. ChatKit provides a managed chat experience with thread management, session authentication, and workflow integration.

Code Reference

Source Location

• Repository: openai-node
• File: src/resources/beta/chatkit/threads.ts

Signature

export class Threads extends APIResource {
  retrieve(threadID: string, options?: RequestOptions): APIPromise<ChatKitThread>;

  list(
    query?: ThreadListParams | null | undefined,
    options?: RequestOptions,
  ): PagePromise<ChatKitThreadsPage, ChatKitThread>;

  delete(threadID: string, options?: RequestOptions): APIPromise<ThreadDeleteResponse>;

  listItems(
    threadID: string,
    query?: ThreadListItemsParams | null | undefined,
    options?: RequestOptions,
  ): PagePromise<ChatKitThreadItemListDataPage, ChatKitThreadItemUnion>;
}

Import

import OpenAI from 'openai';
// Access via client.beta.chatkit.threads

I/O Contract

Inputs

Name	Type	Required	Description
threadID	string	Yes	The identifier of the ChatKit thread (e.g., 'cthr_123')
query.before	string	No	Cursor for pagination; list items created before this ID
query.order	'desc'	No	Sort order by creation time (defaults to 'desc')
query.user	string	No	Filter threads by user identifier (list only)
query.limit	number	No	Number of items per page

Outputs

Name	Type	Description
ChatKitThread	ChatKitThread	Thread object with id, title, status, user, created_at, and object type
ChatKitThreadsPage	ConversationCursorPage<ChatKitThread>	Paginated list of ChatKit threads
ThreadDeleteResponse	ThreadDeleteResponse	Confirmation with id, deleted boolean, and object type
ChatKitThreadItemListDataPage	ConversationCursorPage<ThreadItemUnion>	Paginated list of thread items (messages, widgets, tool calls, tasks)

Usage Examples

Basic Usage

import OpenAI from 'openai';

const client = new OpenAI();

// Retrieve a thread
const thread = await client.beta.chatkit.threads.retrieve('cthr_123');

// List threads with pagination
for await (const chatkitThread of client.beta.chatkit.threads.list()) {
  console.log(chatkitThread.id, chatkitThread.title);
}

// List items in a thread
for await (const item of client.beta.chatkit.threads.listItems('cthr_123')) {
  console.log(item.type, item.id);
}

// Delete a thread
const deleted = await client.beta.chatkit.threads.delete('cthr_123');

Related Pages

• Environment:Openai_Openai_node_Node_20_Runtime