Client SDK · State and data

Conversations.

List, retrieve, rename, and rate the threads behind a conversationId.

`conversations.list(options?)`

Lists conversations with pagination.

TypeScript

const result = await client.conversations.list({ limit: 20, offset: 0 });
for (const conv of result.conversations) {
  console.log(`${conv.id}: ${conv.title} (updated ${conv.updatedAt})`);
}

Field	type	description
limit	number	Maximum number of conversations to return.
offset	number	Pagination offset.
fingerprint	string \| null	Device fingerprint.
accessToken	string \| null	Override access token.

Returns Promise<ConversationListResponse>:

TypeScript

interface ConversationListResponse {
  conversations: ConversationSummary[];
  total: number;
  limit: number;
  offset: number;
}

interface ConversationSummary {
  id: string;
  userId: string;
  title: string;
  createdAt: string;
  updatedAt: string;
}

`conversations.retrieve(conversationId, options?)`

Retrieves a full conversation thread with all messages.

TypeScript

const conv = await client.conversations.retrieve('conv-123');
for (const msg of conv.messages) {
  console.log(`[${msg.role}] ${msg.content}`);
}

Returns Promise<ConversationRecord>:

TypeScript

interface ConversationRecord extends ConversationSummary {
  messages: ConversationMessage[];
}

interface ConversationMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  feedback?: 'positive' | 'negative' | null;
  attachments?: FileAttachment[];
  tokensUsed?: number | null;
  parentId?: string | null;
  generationOrdinal?: number;
  status?: 'completed' | 'failed' | 'interrupted';
  errorCode?: string | null;
  createdAt: string;
}

`conversations.update(conversationId, patch, options?)`

Updates a conversation's metadata (currently only title).

TypeScript

await client.conversations.update('conv-123', { title: 'My Chat About AI' });

Field	type	description
conversationId	string	The conversation to update.
patch	{ title?: string }	Fields to update.

Returns Promise<void>.

`conversations.setMessageFeedback(conversationId, messageId, feedback, options?)`

Sets thumbs-up or thumbs-down feedback on a specific message.

TypeScript

await client.conversations.setMessageFeedback('conv-123', 'msg-456', 'positive');

Field	type	description
conversationId	string	The conversation containing the message.
messageId	string	The message to rate.
feedback	'positive' \| 'negative'	The feedback value.

Returns Promise<{ ok: boolean }>.