Threads API
Relevant source files
The following files were used as context for generating this wiki page:
- src/app/api/threads/route.ts
- src/app/api/threads/[id]/route.ts
- src/app/api/threads/[id]/messages/route.ts
- src/app/api/threads/[id]/messages/[messageId]/route.ts
- src/app/api/threads/[id]/title/route.ts
- src/lib/chat/custom-thread-history-adapter.tsx
- src/lib/chat/custom-thread-list-adapter.tsx
- drizzle/0002_deep_shadowcat.sql
The Threads API is a core system within ThinkEx that manages persistent AI conversations. It facilitates the creation, retrieval, and management of chat threads and their associated messages, ensuring that AI reasoning compounds into lasting knowledge rather than being isolated to single sessions.
The system is built on a PostgreSQL backend using Drizzle ORM and exposes a RESTful interface to the frontend. It integrates deeply with the project's workspace-based context, allowing AI assistants to reference specific cards and media within a workspace.
Sources: README.md:16-24, src/app/api/threads/route.ts
Data Architecture
The Threads API relies on two primary database tables: chat_threads and chat_messages. These tables maintain a hierarchical relationship where messages belong to specific threads, which in turn belong to workspaces and users.
Schema Definition
The database schema enforces referential integrity through foreign keys and supports Row Level Security (RLS) to ensure users can only access threads within workspaces they own or collaborate on.
Sources: drizzle/0002_deep_shadowcat.sql:1-41
API Endpoints
The API is structured around thread management and message persistence. All endpoints require authentication and verify workspace access before performing operations.
Thread Management
Threads serve as containers for conversations. They can be created, listed by workspace, renamed, or deleted.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/threads?workspaceId={id} | Lists all threads for a specific workspace. |
POST | /api/threads | Creates a new thread within a workspace. |
GET | /api/threads/[id] | Fetches metadata for a specific thread. |
PATCH | /api/threads/[id] | Updates thread metadata (e.g., title or head message). |
DELETE | /api/threads/[id] | Deletes a thread and all its messages. |
Sources: src/app/api/threads/route.ts:13-90, src/app/api/threads/[id]/route.ts:35-108
Message Operations
Messages are stored with unique messageId strings and support branching through parentId references.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/threads/[id]/messages | Loads messages for a thread, optionally filtered by format. |
POST | /api/threads/[id]/messages | Appends a new message and updates thread timestamps. |
PATCH | /api/threads/[id]/messages/[messageId] | Updates an existing message's content. |
Sources: src/app/api/threads/[id]/messages/route.ts:25-115, src/app/api/threads/[id]/messages/[messageId]/route.ts:30-71
Automatic Title Generation
ThinkEx utilizes the gemini-2.5-flash-lite model to automatically generate descriptive titles for new threads based on the initial conversation context.
When a title is requested via POST /api/threads/[id]/title, the system extracts text from the first six messages of the conversation. If the AI model fails or the conversation is empty, it falls back to a snippet of the first user message or the default string "New Chat".
Client-Side Integration
The frontend interacts with the Threads API through a custom adapter pattern. This allows the UI to maintain a consistent state while handling complex message histories.
Thread History Adapter
The createCustomThreadHistoryAdapter manages the loading and saving of messages. A critical component of this logic is the sortParentsBeforeChildren function, which performs a topological sort on messages. This ensures that when messages are imported into the client-side repository, parent messages are processed before their children, maintaining the correct conversation tree structure.
Thread List Adapter
The createThreadListAdapter provides high-level methods for the assistant-ui library to interact with thread collections. It maps internal API responses to the expected UI format and handles operations like archiving, renaming, and title generation streaming.
Sources: src/lib/chat/custom-thread-list-adapter.tsx:34-118
Conclusion
The Threads API provides the persistent backbone for AI interactions in ThinkEx. By combining a structured PostgreSQL schema with intelligent title generation and specialized client-side adapters, the system ensures that conversations are contextually aware, easily organized, and reliably preserved across user sessions.
Sources: README.md:10-15