API Documentation

Search infrastructure for AI agents. REST API + MCP protocol.

# Quick Start

No API key needed for basic search. Just call the endpoint:

Example

curl https://searchx.dev/api/v1/search?q=kubernetes&mode=hybrid

# Authentication

Free tier works without auth. Pro and Premium require OAuth2 token.

Example

# Get token (Pro/Premium)
curl -X POST https://searchx.dev/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_SECRET" \
  -d "scope=search:read search:semantic"

# Use token
curl -H "Authorization: Bearer TOKEN" \
  https://searchx.dev/api/v1/search?q=test

# Search API

Search across billions of indexed pages with keyword, semantic, or hybrid mode.

Example

GET /api/v1/search

Parameters:
  q         string   required   Search query
  mode      string   hybrid     keyword | semantic | hybrid
  page      int      1          Page number
  per_page  int      10         Results per page (max 50)
  lang      string              Filter by language (en, uz, ru)
  agent     string   general    general | coder | researcher | marketer

Response:
{
  "results": [{
    "url": "https://...",
    "title": "Page Title",
    "snippet": "Highlighted <mark>match</mark>...",
    "score": 0.95,
    "domain": "example.com",
    "language": "en"
  }],
  "total": 42,
  "took_ms": 5,
  "query": "kubernetes",
  "mode": "hybrid",
  "page": 1,
  "per_page": 10
}

# Suggest API

Get autocomplete suggestions for search queries.

Example

GET /api/v1/suggest?q=kube

Response:
{
  "suggestions": [
    "Kubernetes",
    "Kubernetes Pods",
    "Kubernetes Service"
  ]
}

# MCP Server

Connect AI agents to SearchX via MCP protocol. Supports Streamable HTTP and SSE transports.

Example

# MCP Endpoint (Streamable HTTP)
POST https://mcp.searchx.dev/mcp

# MCP Endpoint (SSE)
GET  https://mcp.searchx.dev/mcp

# Health check
GET  https://mcp.searchx.dev/mcp/health

# 6 Tools:
- search(query, mode, agent, page, per_page, language, freshness)
- search_suggest(query)
- search_for_code(query, language)
- search_for_research(query, language)
- search_for_writing(query, language)
- search_for_market(query, language)

# Example: call search tool
curl -X POST https://mcp.searchx.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {"query": "kubernetes", "mode": "hybrid"}
    },
    "id": 1
  }'

# Claude Code / Cursor — use Python MCP client
{
  "mcpServers": {
    "searchx": {
      "command": "python3",
      "args": ["mcp-search-server/server.py"],
      "env": {"SEARCH_API_URL": "https://searchx.dev"}
    }
  }
}

# OAuth2 Scopes

Each tier has different access scopes.

Example

Free:     search:read
Pro:      search:read search:semantic search:suggest
Premium:  search:read search:semantic search:suggest search:rag search:rerank

# Rate Limits

Rate limits depend on your subscription tier.

Example

Free:     10 requests/minute, 100/day
Pro:      Unlimited
Premium:  Unlimited + priority queue