Overview
The search endpoint creates a new chat session and performs an AI-powered web search using Google’s Gemini 2.0 Flash model with grounding capabilities. It returns a formatted answer, source citations, related questions, and relevant images.Endpoints
The search API supports both GET and POST methods:GET /api/search
Perform a simple text-based search using query parameters.Query Parameters
The search query text. URL encoding recommended for special characters.
Search mode that controls response style and length. Valid values:
concise- Brief answers (max 150 tokens, temperature 0.1)default- Balanced responses (max 65536 tokens, temperature 1.2)exhaustive- Comprehensive answers (max 65536 tokens, temperature 0.8)search- Quick factual lookup (max 1024 tokens, temperature 0.4)reasoning- Deep analysis (max 65536 tokens, temperature 1.0)
Request Example
Response
Unique identifier for the chat session. Use this for follow-up questions.
HTML-formatted answer generated by the AI. Includes markdown-to-HTML conversion with proper headers, lists, and paragraphs.
Array of web sources used to ground the answer.
Array of 3 related follow-up questions suggested by the AI
Array of relevant images found for the query.
Response Example
POST /api/search
Perform advanced searches with reasoning context, language preferences, and image uploads.Request Body
The search query text
Search mode (same options as GET endpoint)
Optional reasoning analysis from the
/api/reasoning endpoint. When provided, the search uses this context to guide answer generation.Target language for the response (e.g., “Spanish”, “French”, “Japanese”). The AI will respond in the specified language.
Array of images to include in the search context (multimodal search).
Request Example
Request Example with Reasoning
Response
Identical to GET endpoint response format.Error Responses
400 Bad Request
500 Internal Server Error
Search Modes Explained
Concise Mode
Best for: Quick facts, definitions, simple questions Characteristics:- Very short responses (max 150 tokens)
- Low temperature (0.1) for focused answers
- Deterministic output (topK: 1)
Default Mode
Best for: General questions, balanced detail Characteristics:- Full-length responses (max 65536 tokens)
- Higher temperature (1.2) for creative, comprehensive answers
- Balanced parameters (topP: 0.95, topK: 40)
Exhaustive Mode
Best for: Research, in-depth analysis, comprehensive coverage Characteristics:- Full-length responses (max 65536 tokens)
- Medium temperature (0.8) for detailed but focused answers
- Encourages thorough exploration
Search Mode
Best for: Quick lookups, specific facts, direct answers Characteristics:- Medium-length responses (max 1024 tokens)
- Low temperature (0.4) for accurate retrieval
- Optimized for factual queries
Reasoning Mode
Best for: Complex problems, analytical questions, step-by-step explanations Characteristics:- Full-length responses (max 65536 tokens)
- High temperature (1.0) for exploratory reasoning
- Structured problem-solving approach
Session Management
Each search creates a new chat session with:- Unique session ID (6-character alphanumeric string)
- In-memory storage of chat history
- Google Search tool enabled
- Optional image context (for POST requests with
user_images)
Technical Details
Response Processing Pipeline
- Query execution: Gemini 2.0 Flash with Google Search tool
- Content extraction: Parse response text, related questions, and images
- Markdown formatting: Convert raw text to structured markdown
- HTML conversion: Use
markedlibrary to render HTML - Source extraction: Parse grounding metadata for citations
- Session creation: Generate ID and store chat session
Grounding Metadata
The API automatically extracts source citations from Gemini’s grounding metadata:groundingChunks: Web sources used by the modelgroundingSupports: Text segments linked to specific sources- Automatic deduplication of sources by URL
- Snippet extraction showing which parts of the answer reference each source
Next Steps
Reasoning
Add reasoning analysis before searching
Follow-up
Continue conversations with follow-up questions