Skip to main content

​
Introduction

The OmniSearches API provides powerful endpoints for performing AI-powered web searches, reasoning analysis, and follow-up conversations. Built on Google’s Gemini 2.0 Flash model with grounding capabilities, it delivers accurate, cited answers with automatic source extraction.

​
Base URL

All API requests should be made to: 
http://localhost:3000/api
In production, replace localhost:3000 with your deployed server URL.

​
Authentication

The OmniSearches API requires server-side configuration with the following environment variables:
​
GOOGLE_API_KEY
string
required
Google Generative AI API key for Gemini model access
​
REASON_MODEL_API_KEY
string
required
API key for the reasoning model (e.g., DeepSeek)
​
REASON_MODEL_API_URL
string
required
Base URL for the reasoning model API endpoint
​
REASON_MODEL
string
Model identifier for reasoning (defaults to “deepseek-reasoner”)
The API does not currently require client authentication headers. Authentication is managed through server environment configuration.

​
Request Format

All POST requests must include: 
Content-Type: application/json
The API accepts JSON payloads up to 50MB, supporting large image uploads for multimodal search.

​
Response Format

All API responses (except streaming endpoints) return JSON with the following structure:

​
Success Response

{
  "sessionId": "abc123",
  "summary": "<p>HTML formatted answer...</p>",
  "sources": [
    {
      "title": "Source Title",
      "url": "https://example.com",
      "snippet": "Relevant text snippet"
    }
  ],
  "relatedQuestions": [
    "Related question 1?",
    "Related question 2?",
    "Related question 3?"
  ],
  "images": [
    {
      "url": "https://example.com/image.jpg",
      "caption": "Image description",
      "alt": "Alt text"
    }
  ]
}

​
Error Response

{
  "message": "Error description"
}
HTTP status codes:
  • 200 - Success
  • 400 - Bad request (missing or invalid parameters)
  • 404 - Resource not found (e.g., invalid session)
  • 500 - Server error

​
Rate Limits

Rate limits depend on your Google Generative AI API quota and reasoning model provider limits. Monitor your API usage through the respective provider dashboards.

​
API Endpoints

Search

Perform AI-powered web searches with multiple modes

Reasoning

Generate search strategies and explanation plans

Follow-up

Continue conversations in existing search sessions

​
Getting Started

  1. Start a search: Use GET /api/search or POST /api/search to perform an initial query
  2. Get reasoning (optional): Use GET /api/reasoning to analyze complex queries before searching
  3. Follow up: Use POST /api/follow-up with the returned sessionId to ask related questions

​
Example Workflow

# 1. Perform initial search
curl "http://localhost:3000/api/search?q=What+is+machine+learning&mode=default"

# Response includes sessionId: "abc123"

# 2. Ask follow-up question
curl -X POST http://localhost:3000/api/follow-up \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "abc123",
    "query": "What are the main types of machine learning?"
  }'

​
Next Steps

Search Endpoint

Explore search modes and parameters

Reasoning Endpoint

Learn about streaming reasoning analysis

Build docs developers (and LLMs) love

Get started for freeTalk to us