---
title: "Search Chat Messages"
method: GET
path: "/api/chats/search-messages"
tags: ["chats"]
---

# Search Chat Messages

`GET /api/chats/search-messages`

## Request

- Base URL: `https://app.thinqos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://app.thinqos.com/api/chats/search-messages`
- Auth: none declared

Search the CONTENT of the caller's own conversations (TOS-2330).

``GET /api/chats?q=`` only substring-matches chat titles and participant
display names, so a word the user remembers from inside a conversation
finds nothing there no matter how far they page. This exposes the corpus
search that already backs the agent-facing ``conversation_search`` MCP tool
(TOS-477) to the user's own UI.

Scope is ``agent = person = caller``, exactly as ``conversation_search``'s
self-recall path does (TOS-844 P1): ``_scope_chat_ids`` then resolves to
chats where the CALLER is an active participant. Nothing outside the
caller's own participated chats is reachable and no new privacy SQL is
introduced. ``include_excluded=True`` keeps ``extraction_excluded``
messages, which govern Mind-extraction subject scope rather than the user's
own visibility - without it the user could not search their own captured
Claude Code / Codex sessions.

**Lexical only (TOS-3138).** The semantic leg is deliberately off for this
surface. Measured on prod over a 16,885-chat corpus, it returns a full page
of unrelated segments for a query that matches nothing, at cosine scores
ABOVE those of genuine matches for real queries - so no threshold separates
them and the "No message matches" empty state was unreachable. The lexical
legs fired 4x for each real query and 0-1x for each nonsense one. A search
box wants that precision; agent recall keeps the full hybrid, where a loose
hit is cheaper than a miss. Consequence: no query embedding is computed, so
this endpoint makes no AI call at all.

## Query parameters

- `q` string, required
- `limit` integer

## Headers

- `x-impersonate-identity-id` string, nullable

## Response `200`

Successful Response

- MessageSearchResponse
  - `hits` MessageSearchHit[], required
    - `chat_id` string, uuid, required
    - `chat_title` string, nullable
    - `message_id` string, uuid, nullable
    - `occurred_at` string, date-time, required
    - `sender_role` string, nullable
    - `excerpt` string, required
    - `source` string, required
  - `degraded` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/thinqos/apis/thinqos-api.md) · [All operations](https://skmtc.dev/thinqos/apis/thinqos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinqos/apis/thinqos-api/revisions/ce2c2ce318b1?raw)