---
title: "Search chats"
method: GET
path: "/chat/search"
tags: ["Chat"]
---

# Search chats

`GET /chat/search`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/chat/search`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/chat/search/get.ts> (a function with typed inputs; its response is checked against the schema)

Hybrid search across the caller's chat history that merges two lanes: a case-insensitive title-substring match and a semantic (vector) match over each chat's AI-generated summary. Title matches are returned first (a strong signal the user remembers the chat name), followed by semantic matches in relevance order, de-duplicated and capped at `limit`.

**Authorization:** User-scoped keys (`u:gcai_...`) search the chats that user can access. Organization-scoped keys search every chat shared with the entire organization, regardless of who or what created it. Chats that remain private to an individual user are never returned to an org-scoped key.

API-created chats appear here only once they've been [materialized](https://docs.gc.ai/api-reference/concepts/chat-visibility); unmaterialized chats are not in anyone's history and won't match.

## Query parameters

- `q` string, required: Search query (required, 1-500 chars). Natural language is fine.
- `limit` integer: Max chats to return (default 20, max 50)

## Response `200`

Chats matching the query

- ChatSearchResponse
  - `chats` ChatSearchResult[], required: Chats matching the query. Title-substring matches first, then semantic (vector) matches in relevance order, de-duplicated and capped at `limit`.
    - `id` string, uuid, required: Unique chat identifier
    - `title` string, nullable, required: Chat title, or null if untitled
    - `summary` string, nullable, required: AI-generated summary of the chat, if any
    - `updated_at` string, required: ISO 8601 last-update timestamp
  - `soft_threshold_fallback` boolean, required: True when no semantic match cleared the relevance cutoff and the response includes the closest below-threshold candidates instead of omitting them.

## Other responses

- `400`: Missing or invalid query parameters
- `401`: Missing or malformed API key
- `403`: User API key does not include Chat access
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)