Query user's unified context with AI

Performs semantic retrieval across the user's connected messages, meetings, and calendar events, then returns an AI-generated answer.

Billing: This endpoint is metered. Each call consumes AI query credits.

Use cases:

• "What did Sarah say about the Q4 budget?"
• "Summarize my meeting with the engineering team last Tuesday"
• "Find all discussions about the product launch"

Parameters:

• query: The natural language question to answer (max 10,000 characters)
• client_timezone: User's timezone for date-aware queries
• history: Optional conversation history for follow-up questions (capped at 50 items / 64KB UTF-8; oldest are dropped past the cap with a history_truncated_for_size_budget warning, and a single message above the byte cap is rejected with VALIDATION_OUT_OF_RANGE)
• integration_ids: Optional filter to specific integrations (opaque IDs like int_xxx)
• conversation_ids: Optional filter to specific conversations (opaque IDs, e.g., "conv_xxx")
• retrieval_mode: Optional retrieval strategy — "fast" (lowest latency), "auto" (adaptive, default), or "deep" (full pipeline)
• expand: Optional comma-separated fields to include (e.g., "sources")
• instructions: Optional custom instructions for the AI (controls output format, filtering, conditional behavior — overrides default style, max 20,000 chars)
• context: Optional authoritative reference data the AI treats as ground truth (influences query rewriting but not used for vector search, max 20,000 chars)

Response structure:

• answer: AI-generated answer text
• used_message_ids: Message IDs (msg_xxx) used as source context
• used_meeting_ids: Meeting IDs (mtg_xxx) used as source context
• used_event_ids: Event IDs (evt_xxx) used as source context
• used_note_ids: Note IDs (note_xxx) used as source context
• sources: Optional human-readable snippets (only with expand=sources)
• If no relevant context is found, the request still succeeds with a plain-language answer and empty source ID arrays.

Expand parameter: By default, sources (title/snippet pairs) are not included to reduce payload size. Use expand=sources to include source snippets for display purposes.