> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Search conversations > Full-transcript hybrid search (lexical BM25 + dense vector, reciprocal-rank fused, then cross-encoder reranked) over the caller's conversations within their workspace. Returns message-level hits - each carries the conversation, the matched message's sequence number (a jump-to-message deep link), a highlighted snippet, and a relevance score - newest-relevance first. Scoped to conversations the caller participates in. Cursor-paginated. ## OpenAPI ````yaml GET /v1/api/search openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/api/search: get: tags: - search summary: Search conversations description: >- Full-transcript hybrid search (lexical BM25 + dense vector, reciprocal-rank fused, then cross-encoder reranked) over the caller's conversations within their workspace. Returns message-level hits - each carries the conversation, the matched message's sequence number (a jump-to-message deep link), a highlighted snippet, and a relevance score - newest-relevance first. Scoped to conversations the caller participates in. Cursor-paginated. operationId: search_conversations parameters: - name: q in: query description: >- Free-text query. Searches the full message transcript, not just titles. required: true schema: type: string - name: limit in: query description: Max hits to return (default 20, max 50). required: false schema: type: - integer - 'null' minimum: 0 - name: cursor in: query description: Opaque forward-pagination cursor from a previous response. required: false schema: type: - string - 'null' - name: channel_kind in: query description: >- Restrict to one channel: `slack` | `teams` | `web` | `api` | `cli` | `email`. required: false schema: type: - string - 'null' - name: agent in: query description: Restrict to one agent (slug). required: false schema: type: - string - 'null' - name: mode in: query description: >- Lane filter: `fast` (quick-ask threads) | `standard` | `all` (default all). required: false schema: type: - string - 'null' responses: '200': description: Ranked message-level search hits content: application/json: schema: $ref: '#/components/schemas/SearchResp' security: - bearer_pat: - conversations:read - oauth2: - conversations:read components: schemas: SearchResp: type: object required: - hits - took_ms properties: hits: type: array items: $ref: '#/components/schemas/SearchHit' next_cursor: type: - string - 'null' description: Pass back as `cursor` to fetch the next page; null when exhausted. took_ms: type: integer format: int64 minimum: 0 SearchHit: type: object required: - conversation_id - channel_kind - seq - snippet - score - matched_at properties: agent: oneOf: - type: 'null' - $ref: '#/components/schemas/AgentRef' description: The agent on the conversation, when present. channel_kind: type: string conversation_id: type: string format: uuid description: Conversation the matched message belongs to. matched_at: type: string format: date-time description: When the matched message was created. score: type: number format: float description: Post-rerank relevance, higher is better. seq: type: integer format: int64 description: |- Per-conversation sequence number of the matched message - the jump-to-message deep-link target. snippet: type: string description: Highlighted excerpt around the match (`…`). title: type: - string - 'null' description: Conversation title (LLM-derived label); null if not yet titled. AgentRef: type: object required: - slug - display_name properties: display_name: type: string slug: type: string securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````