---
title: "Search Chats Tiered"
method: GET
path: "/api/chats/search"
tags: ["chats"]
---

# Search Chats Tiered

`GET /api/chats/search`

## 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`
- Auth: none declared

Ranked, tiered search over the caller's conversations (TOS-3459).

``GET /api/chats?q=`` remains the BROWSE surface: a boolean substring filter
over a recency-ordered keyset page, still used for infinite scroll and the
"Show all" fallback. This endpoint is the SEARCH surface, and differs in
three ways that the old one could not express:

- **Ranked by match quality**, not recency. An exact title match outranks a
  newer partial one; recency is only the tiebreak.
- **People and agents are their own tier**, grouped one row per identity
  with a conversation count, rather than scattered across title-less rows.
- **Near-misses are reachable.** ``council`` finds ``AI4O General Counsel``
  via trigram similarity, in a tier explicitly labelled as a suggestion and
  returned only when the exact tiers are thin.

Archived conversations are included and flagged ``archived`` rather than
excluded - a search is an explicit retrieval intent, so "it exists but is
filed away" beats "no matches". This does not change the archived/unarchived
tabs, which still scope browsing.

Makes no AI call: ``pg_trgm`` similarity and SQL ordering only.

## Query parameters

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

## Headers

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

## Response `200`

Successful Response

- ChatSearchResponse: Tiered search results: people, then conversations, then near-misses.
  - `query` string, required
  - `people` IdentitySearchHit[], required
    - `identity_id` string, uuid, required
    - `display_name` string, required
    - `avatar_url` string, nullable
    - `kind` string, required
    - `chat_count` integer, required
    - `last_activity_at` string, date-time, nullable
    - `similarity` number, nullable
  - `conversations` ChatSearchHit[], required
    - `chat_id` string, uuid, required
    - `title` string, nullable
    - `last_message_at` string, date-time, nullable
    - `archived` boolean
    - `match_reason` string, required
    - `matched_participant_name` string, nullable
  - `did_you_mean` IdentitySearchHit[], required
    - `identity_id` string, uuid, required
    - `display_name` string, required
    - `avatar_url` string, nullable
    - `kind` string, required
    - `chat_count` integer, required
    - `last_activity_at` string, date-time, nullable
    - `similarity` number, nullable
  - `people_total` integer, required
  - `conversations_total` integer, required
  - `people_truncated` boolean, required
  - `conversations_truncated` boolean, required

## 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)