Chat Thread Search: Agent Mode and Turn Context

Search chat threads with an enhanced agent mode that returns larger content snippets, filters out tool metadata, and includes turn numbers for precise conversation navigation. A new thread context endpoint lets you fetch full conversation content around a specific turn.

What's New

Agent search mode: Pass mode=agent to get 500-character snippets (vs 100 in UI mode), exclude tool message noise, and receive turnNumber for each match
Thread context endpoint: Fetch full human/AI conversation content from a thread with configurable turn windowing — ideal for drilling into search results

New Endpoint

GET /api/v1/accounts/{accountId}/workspaces/{workspaceId}/chat-threads/{threadId}/context

Modified Endpoint

GET /api/v1/accounts/{accountId}/workspaces/{workspaceId}/chat-threads/search — new mode query parameter and turnNumber response field

Search: New Query Parameter

Parameter	Type	Default	Description
`mode`	`"ui"` \| `"agent"`	`"ui"`	Controls snippet size, message filtering, turnNumber

Search: Updated Response

Each result now includes:

{
  "threadId": "550e8400-...",
  "title": "Revenue by region",
  "snippet": "SELECT region, SUM(revenue) FROM sales GROUP BY region...",
  "matchedIn": "content",
  "turnNumber": 3,
  "createdAt": "2026-02-10T14:30:00Z",
  "updatedAt": "2026-02-10T14:35:00Z"
}

turnNumber is populated in agent mode only (null in UI mode).

Thread Context: Request

Parameter	Type	Default	Description
`userId`	string?	—	Clerk user ID (M2M only)
`turnNumber`	int?	—	Center of context window; omit for latest turns
`window`	int	1	Turns before/after turnNumber to include (0–3)

Thread Context: Response

{
  "threadId": "550e8400-...",
  "title": "Revenue by region",
  "turns": [
    {
      "turnNumber": 2,
      "messages": [
        { "type": "human", "text": "Show me revenue by region" },
        { "type": "ai", "text": "I'll query the sales table..." }
      ]
    },
    {
      "turnNumber": 3,
      "messages": [
        { "type": "human", "text": "Can you add a filter for Q2?" },
        { "type": "ai", "text": "SELECT region, SUM(revenue)..." }
      ]
    }
  ]
}

Getting Started

Use mode=agent when searching programmatically to get richer snippets
When a search result is relevant but the snippet lacks detail, call the context endpoint with the threadId and turnNumber from the search result
Adjust window (0–3) to control how much surrounding conversation to fetch