0
# ChatKit (Beta)
1

2
ChatKit provides a simplified, high-level interface for building chat applications with OpenAI models. It abstracts away common patterns and provides session and thread management out of the box.
3

4
**Note**: ChatKit is a beta feature and the API may change.
5

6
## Capabilities
7

8
### Create ChatKit Session
9

10
Create a new ChatKit session for managing a chat conversation with a specified workflow.
11

12
```python { .api }
13
def create(
14
    self,
15
    *,
16
    user: str,
17
    workflow: ChatSessionWorkflowParam,
18
    chatkit_configuration: ChatSessionChatKitConfigurationParam | Omit = omit,
19
    expires_after: ChatSessionExpiresAfterParam | Omit = omit,
20
    rate_limits: ChatSessionRateLimitsParam | Omit = omit,
21
    extra_headers: dict[str, str] | None = None,
22
    extra_query: dict[str, object] | None = None,
23
    extra_body: dict[str, object] | None = None,
24
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
25
) -> ChatSession:
26
    """
27
    Create a ChatKit session with a workflow and configuration.
28

29
    Args:
30
        user: A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope.
31
        workflow: Workflow that powers the session. Must include an `id` field (workflow identifier) and optionally `state_variables`, `tracing`, and `version`.
32
        chatkit_configuration: Optional overrides for ChatKit runtime configuration features including automatic thread titling, file upload settings, and history management.
33
        expires_after: Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes (600 seconds).
34
        rate_limits: Optional override for per-minute request limits. When omitted, defaults to 10 requests per minute.
35
        extra_headers: Additional HTTP headers.
36
        extra_query: Additional query parameters.
37
        extra_body: Additional JSON fields.
38
        timeout: Request timeout in seconds.
39

40
    Returns:
41
        ChatSession: Created session with configuration, client secret, and workflow metadata.
42
    """
43
```
44

45
### Cancel ChatKit Session
46

47
Cancel an active ChatKit session and release resources.
48

49
```python { .api }
50
def cancel(
51
    self,
52
    session_id: str,
53
    *,
54
    extra_headers: dict[str, str] | None = None,
55
    extra_query: dict[str, object] | None = None,
56
    extra_body: dict[str, object] | None = None,
57
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
58
) -> ChatSession:
59
    """
60
    Cancel a ChatKit session.
61

62
    Args:
63
        session_id: The ID of the session to cancel.
64
        extra_headers: Additional HTTP headers.
65
        extra_query: Additional query parameters.
66
        extra_body: Additional JSON fields.
67
        timeout: Request timeout in seconds.
68

69
    Returns:
70
        ChatSession: Session with status "cancelled".
71
    """
72
```
73

74
Usage example:
75

76
```python
77
from openai import OpenAI
78

79
client = OpenAI()
80

81
# Create a ChatKit session with a workflow
82
session = client.beta.chatkit.sessions.create(
83
    user="user_12345",
84
    workflow={
85
        "id": "workflow_abc123",
86
        "state_variables": {"context": "customer_support"},
87
        "version": "v1.0"
88
    }
89
)
90

91
print(f"Session ID: {session.id}")
92
print(f"Status: {session.status}")
93
print(f"User: {session.user}")
94
print(f"Expires at: {session.expires_at}")
95

96
# Cancel session when done
97
cancelled = client.beta.chatkit.sessions.cancel(session.id)
98
print(f"Cancelled: {cancelled.status}")
99
```
100

101
### Retrieve ChatKit Thread
102

103
Get details of a specific ChatKit thread.
104

105
```python { .api }
106
def retrieve(
107
    self,
108
    thread_id: str,
109
    *,
110
    extra_headers: dict[str, str] | None = None,
111
    extra_query: dict[str, object] | None = None,
112
    extra_body: dict[str, object] | None = None,
113
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
114
) -> ChatKitThread:
115
    """
116
    Retrieve a ChatKit thread by ID.
117

118
    Args:
119
        thread_id: The ID of the thread to retrieve.
120
        extra_headers: Additional HTTP headers.
121
        extra_query: Additional query parameters.
122
        extra_body: Additional JSON fields.
123
        timeout: Request timeout in seconds.
124

125
    Returns:
126
        ChatKitThread: Thread object with messages and metadata.
127
    """
128
```
129

130
### List ChatKit Threads
131

132
List all ChatKit threads for the current organization.
133

134
```python { .api }
135
def list(
136
    self,
137
    *,
138
    after: str | Omit = omit,
139
    before: str | Omit = omit,
140
    limit: int | Omit = omit,
141
    order: Literal["asc", "desc"] | Omit = omit,
142
    user: str | Omit = omit,
143
    extra_headers: dict[str, str] | None = None,
144
    extra_query: dict[str, object] | None = None,
145
    extra_body: dict[str, object] | None = None,
146
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
147
) -> SyncConversationCursorPage[ChatKitThread]:
148
    """
149
    List ChatKit threads with pagination.
150

151
    Args:
152
        after: Return threads after this thread ID (for forward pagination).
153
        before: Return threads before this thread ID (for backward pagination).
154
        limit: Maximum number of threads to return (default 20, max 100).
155
        order: Sort order: "asc" (oldest first) or "desc" (newest first, default).
156
        user: Filter threads that belong to this user identifier (defaults to null for all users).
157
        extra_headers: Additional HTTP headers.
158
        extra_query: Additional query parameters.
159
        extra_body: Additional JSON fields.
160
        timeout: Request timeout in seconds.
161

162
    Returns:
163
        SyncConversationCursorPage[ChatKitThread]: Paginated list of threads with cursor-based navigation.
164
    """
165
```
166

167
### Delete ChatKit Thread
168

169
Delete a ChatKit thread and all its messages.
170

171
```python { .api }
172
def delete(
173
    self,
174
    thread_id: str,
175
    *,
176
    extra_headers: dict[str, str] | None = None,
177
    extra_query: dict[str, object] | None = None,
178
    extra_body: dict[str, object] | None = None,
179
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
180
) -> ThreadDeleteResponse:
181
    """
182
    Delete a ChatKit thread.
183

184
    Args:
185
        thread_id: The ID of the thread to delete.
186
        extra_headers: Additional HTTP headers.
187
        extra_query: Additional query parameters.
188
        extra_body: Additional JSON fields.
189
        timeout: Request timeout in seconds.
190

191
    Returns:
192
        ThreadDeleteResponse: Deletion confirmation with deleted=True.
193
    """
194
```
195

196
### List Thread Items
197

198
List messages and events within a ChatKit thread.
199

200
```python { .api }
201
def list_items(
202
    self,
203
    thread_id: str,
204
    *,
205
    after: str | Omit = omit,
206
    before: str | Omit = omit,
207
    limit: int | Omit = omit,
208
    order: Literal["asc", "desc"] | Omit = omit,
209
    extra_headers: dict[str, str] | None = None,
210
    extra_query: dict[str, object] | None = None,
211
    extra_body: dict[str, object] | None = None,
212
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
213
) -> SyncPage[ChatKitThreadItem]:
214
    """
215
    List items (messages and events) in a ChatKit thread.
216

217
    Args:
218
        thread_id: The ID of the thread.
219
        after: Return items after this item ID.
220
        before: Return items before this item ID.
221
        limit: Maximum number of items to return (default 20, max 100).
222
        order: Sort order: "asc" (chronological) or "desc" (reverse chronological).
223
        extra_headers: Additional HTTP headers.
224
        extra_query: Additional query parameters.
225
        extra_body: Additional JSON fields.
226
        timeout: Request timeout in seconds.
227

228
    Returns:
229
        SyncPage[ChatKitThreadItem]: Paginated list of thread items.
230
    """
231
```
232

233
## Complete Usage Example
234

235
```python
236
from openai import OpenAI
237

238
client = OpenAI()
239

240
# Create a session with a workflow
241
session = client.beta.chatkit.sessions.create(
242
    user="user_12345",
243
    workflow={
244
        "id": "workflow_xyz",
245
        "state_variables": {"mode": "qa"}
246
    },
247
    rate_limits={"per_minute": 20}
248
)
249

250
print(f"Session created: {session.id}")
251
print(f"Client secret: {session.client_secret}")
252

253
# List all threads
254
threads = client.beta.chatkit.threads.list(limit=10)
255
for thread in threads.data:
256
    print(f"Thread: {thread.id}, Created: {thread.created_at}")
257

258
# Retrieve a specific thread
259
if threads.data:
260
    thread = client.beta.chatkit.threads.retrieve(threads.data[0].id)
261
    print(f"Thread metadata: {thread.metadata}")
262

263
    # List items in the thread
264
    items = client.beta.chatkit.threads.list_items(thread.id, order="asc")
265
    for item in items.data:
266
        print(f"Item: {item.type} - {item.content}")
267

268
    # Delete thread when no longer needed
269
    deleted = client.beta.chatkit.threads.delete(thread.id)
270
    print(f"Deleted: {deleted.deleted}")
271

272
# Cancel session
273
client.beta.chatkit.sessions.cancel(session.id)
274
```
275

276
## Types
277

278
```python { .api }
279
from typing import Literal, Dict, Union
280
from pydantic import BaseModel
281

282
# Session related types
283
class ChatSessionWorkflowParam:
284
    """Workflow parameter for ChatKit session."""
285
    id: str  # Required: Identifier for the workflow
286
    state_variables: Dict[str, Union[str, bool, float]] | None  # State variables forwarded to workflow
287
    tracing: dict | None  # Optional tracing overrides (enabled by default)
288
    version: str | None  # Specific workflow version (defaults to latest)
289

290
class ChatSessionChatKitConfigurationParam:
291
    """Optional ChatKit runtime configuration."""
292
    automatic_thread_titling: dict | None  # Configuration for automatic thread title generation
293
    file_upload: dict | None  # File upload settings
294
    history: dict | None  # History management settings
295

296
class ChatSessionExpiresAfterParam:
297
    """Session expiration configuration."""
298
    # Typically a dict with duration in seconds
299

300
class ChatSessionRateLimitsParam:
301
    """Rate limiting configuration."""
302
    per_minute: int | None  # Requests per minute limit
303

304
class ChatSession(BaseModel):
305
    """ChatKit session object."""
306
    id: str
307
    """Identifier for the ChatKit session."""
308

309
    object: Literal["chatkit.session"]
310
    """Type discriminator that is always `chatkit.session`."""
311

312
    chatkit_configuration: dict
313
    """Resolved ChatKit feature configuration for the session."""
314

315
    client_secret: str
316
    """Ephemeral client secret that authenticates session requests."""
317

318
    expires_at: int
319
    """Unix timestamp (in seconds) for when the session expires."""
320

321
    max_requests_per_1_minute: int
322
    """Convenience copy of the per-minute request limit."""
323

324
    rate_limits: dict
325
    """Resolved rate limit values."""
326

327
    status: str
328
    """Current lifecycle state of the session (e.g., "active", "cancelled")."""
329

330
    user: str
331
    """User identifier associated with the session."""
332

333
    workflow: dict
334
    """Workflow metadata for the session."""
335

336
class ChatKitThread(BaseModel):
337
    """ChatKit thread object."""
338
    id: str
339
    object: Literal["chatkit.thread"]
340
    created_at: int
341
    metadata: dict[str, str] | None
342
    session_id: str | None
343

344
class ThreadDeleteResponse(BaseModel):
345
    """Thread deletion confirmation."""
346
    id: str
347
    object: Literal["chatkit.thread"]
348
    deleted: bool
349

350
class ChatKitThreadItem(BaseModel):
351
    """Item within a ChatKit thread (message or event)."""
352
    id: str
353
    object: Literal["chatkit.thread.item"]
354
    type: Literal["message", "event"]
355
    content: str | dict
356
    role: Literal["user", "assistant", "system"] | None
357
    created_at: int
358
    metadata: dict[str, str] | None
359

360
# Pagination
361
class SyncPage[T](BaseModel):
362
    data: list[T]
363
    object: str
364
    first_id: str | None
365
    last_id: str | None
366
    has_more: bool
367
    def __iter__(self) -> Iterator[T]: ...
368
```
369

370
## Best Practices
371

372
1. **Session Management**: Create one session per conversation context and cancel when done to free resources.
373

374
2. **Thread Organization**: Use separate threads for distinct conversation topics or user contexts.
375

376
3. **Metadata**: Leverage metadata for tracking user IDs, session types, or application-specific data.
377

378
4. **Pagination**: When listing threads or items, use pagination parameters to efficiently handle large datasets.
379

380
5. **Error Handling**: Always wrap ChatKit calls in try-except blocks to handle API errors gracefully.
381

382
6. **Resource Cleanup**: Always cancel sessions and delete threads when they're no longer needed.
383

384
```python
385
from openai import OpenAI, APIError
386

387
client = OpenAI()
388

389
try:
390
    session = client.beta.chatkit.sessions.create(
391
        user="user_abc",
392
        workflow={"id": "workflow_123"}
393
    )
394

395
    # Use session...
396

397
finally:
398
    # Clean up
399
    try:
400
        client.beta.chatkit.sessions.cancel(session.id)
401
    except APIError:
402
        pass  # Session may already be cancelled
403
```
404