API Documentation

Base URL:    https://searchx.dev
Auth:        Authorization: Bearer sk-sx-YOUR_KEY

Web Search:
  GET /api/v1/search          — hybrid web search (BM25 + semantic + SearXNG)
  GET /api/v1/images/search   — image search (keyword + semantic)
  GET /api/v1/suggest         — autocomplete suggestions

Category Search (100+ sources, parallel):
  GET /api/v1/hotels          — hotels (Booking, Expedia, Agoda, 15+ sources)
  GET /api/v1/flights         — flights (Skyscanner, Kayak, Aviasales, 16 sources)
  GET /api/v1/jobs            — jobs (Indeed, LinkedIn, Greenhouse, 39+ sources)
  GET /api/v1/shopping        — products (Amazon, eBay, Uzum, 23+ sources)
  GET /api/v1/news            — news articles (Google News, BBC, Reuters)
  GET /api/v1/videos          — video search

Content Extraction:
  GET /api/v1/extract         — URL → clean markdown + metadata
  GET /api/v1/extract?chunked=true  — large docs → paginated chunks
  GET /api/v1/extract?find=X  — find specific term in chunks
  GET /api/v1/web_lookup      — search + parallel fetch + find (composite)
  GET /api/v1/answer          — AI answer with citations

Realtime:
  POST /api/v1/search/box     — create realtime search box
  GET  /api/v1/search/box/{id}       — poll results
  GET  /api/v1/search/box/{id}/stream — SSE stream

Protocols:
  REST API    — all endpoints above
  MCP         — https://mcp.searchx.dev/mcp (12 tools)
  gRPC-Web    — /searchx.SearchService/

SDKs:
  pip install searchx          # Python
  npm install searchx          # Node.js / TypeScript

# Option A: sign up via the web UI (recommended)
# → https://searchx.dev/signup
#   then view your credentials at https://searchx.dev/dashboard

# Option B: sign up via the API (email only)
curl -X POST "https://searchx.dev/api/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# Response:
{
  "email": "you@example.com",
  "tier": "free",
  "client_id": "sx-free-abc123def456",
  "client_secret": "a1b2c3d4e5f6...",
  "token_url": "https://searchx.dev/oauth2/token",
  "scopes": "search:read",
  "rate_limit": 60,
  "daily_limit": 3000
}

curl -X POST "https://searchx.dev/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=sx-free-abc123def456" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=search:read"

# Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "search:read"
}

# Save it to an env var — all examples below use $TOKEN:
export TOKEN="eyJhbGciOiJSUzI1NiIs..."

Endpoint:  GET https://searchx.dev/api/v1/search
Scope:     search:read

Parameters:
  q            string   required   Search query
  mode         string   hybrid     hybrid | keyword | semantic
  page         int      1          Page number
  per_page     int      10         Results per page (max 20)
  lang         string              en, uz, ru, de, fr, es, it, ...
  freshness    string              day | week | month | year
  safe_search  bool     true       Pass "false" to disable
  agent        string              Agent hint for ranking

# Example:
curl -G "https://searchx.dev/api/v1/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=kubernetes deployment" \
  --data-urlencode "mode=hybrid" \
  --data-urlencode "lang=en" \
  --data-urlencode "per_page=2"

# Real response:
{
  "query": "kubernetes deployment",
  "mode": "hybrid",
  "page": 1,
  "per_page": 2,
  "total": 40,
  "took_ms": 849,
  "results": [
    {
      "url": "https://v1-32.docs.kubernetes.io/zh-cn/docs/concepts/cluster-administration/proxies/",
      "title": "Proxies in Kubernetes",
      "snippet": "Kubernetes proxies forward traffic...",
      "score": 1268.06,
      "domain": "v1-32.docs.kubernetes.io",
      "language": "en",
      "trust_score": 0.96,
      "citation": "[Proxies in Kubernetes](...) — v1-32.docs.kubernetes.io",
      "metadata": {"source_type": "documentation"}
    }
  ]
}

Endpoint:  GET https://searchx.dev/api/v1/images/search
Scope:     search:read

Parameters:
  q            string   required   Search query
  page         int      1          Page number
  per_page     int      24         Results per page (max 96)
  safe         string   strict     strict | moderate | off
  min_width    int                 Minimum image width
  min_height   int                 Minimum image height

# Example:
curl -G "https://searchx.dev/api/v1/images/search" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=red Ferrari" \
  --data-urlencode "per_page=2"

# Response:
{
  "query": "red Ferrari",
  "page": 1,
  "per_page": 2,
  "total": 2,
  "took_ms": 3,
  "safe": "strict",
  "results": [
    {
      "url": "https://lmgfl.com/.../RALV0345.jpg",
      "page_url": "https://lmgfl.com/stories-parkland/",
      "alt": "A red Ferrari convertible sports car...",
      "domain": "lmgfl.com",
      "score": 0.016,
      "source": "keyword"
    }
  ]
}

Category Endpoints:
  GET /api/v1/hotels        — hotels (Booking, Expedia, Agoda + 15 sources)
  GET /api/v1/flights       — flights (Skyscanner, Kayak, Aviasales)
  GET /api/v1/jobs          — jobs (Indeed, LinkedIn, Greenhouse + 39 sources)
  GET /api/v1/shopping      — products (Amazon, eBay, Uzum + 18 sources)
  GET /api/v1/news          — news (Google News, BBC, Reuters)
  GET /api/v1/videos        — videos

Common Parameters:
  per_page   int      10         Results per page (max 50)
  enrich     bool     false      AI synthesis from multiple sources
  deep       bool     false      Deep scrape + provider parsing

Hotels:    city (required), checkin, checkout, guests, rooms
Flights:   from (required), to, date, return_date, passengers, class
Jobs:      title (required), location, remote, type, salary
Shopping:  product (required), min_price, max_price, brand

# Hotels:
curl "$BASE/api/v1/hotels?city=Istanbul&checkin=2026-06-01&checkout=2026-06-05"

# Flights:
curl "$BASE/api/v1/flights?from=NYC&to=London&date=2026-06-01"

# Jobs:
curl "$BASE/api/v1/jobs?title=python+developer&location=remote"

# Shopping:
curl "$BASE/api/v1/shopping?product=macbook+pro+m4"

# Response:
{
  "results": [...],
  "total": 25,
  "took_ms": 3500,
  "category": "jobs",
  "mode": "searxng",
  "params": {"title": "python developer", "location": "remote"}
}

Endpoint:  GET  /api/v1/extract
           POST /api/v1/extract

Parameters:
  url         string   required   URL to fetch
  render      string              "static" for fast static fetch (default: auto JS)
  enrich      string              "true" → AI summary, entities, sentiment
  max_length  int      50000      Max content bytes

# HTML page (auto JS rendering for SPAs):
curl -H "Authorization: Bearer sk-sx-YOUR_KEY" \
  "https://searchx.dev/api/v1/extract?url=https://daryo.uz/article"

# PDF document:
curl -H "Authorization: Bearer sk-sx-YOUR_KEY" \
  "https://searchx.dev/api/v1/extract?url=https://arxiv.org/pdf/2305.10973"

# Image (AI vision description):
curl -H "Authorization: Bearer sk-sx-YOUR_KEY" \
  "https://searchx.dev/api/v1/extract?url=https://example.com/photo.jpg"

# With AI enrichment:
curl -H "Authorization: Bearer sk-sx-YOUR_KEY" \
  "https://searchx.dev/api/v1/extract?url=https://daryo.uz/article&enrich=true"

# Response for HTML:
{
  "title": "Article Title",
  "description": "Article description...",
  "author": "Author Name",
  "published_at": "2026-04-17 14:50:00",
  "language": "uz-Latn-UZ",
  "content_type": "news",
  "quality_score": 0.9,
  "word_count": 400,
  "markdown": "Clean article text...",
  "images": ["https://..."],
  "links": ["https://..."],
  "citation": "[Title](url) by Author — Site",
  "engine": "chromium",
  "summary": "AI summary (when enrich=true)",
  "entities": ["Person", "Org", "Place"],
  "sentiment": "neutral"
}

# Response for PDF:
{ "content_type": "pdf", "word_count": 8526, "engine": "pdf", "meta": {"pages": "12"} }

# Response for Image:
{ "content_type": "image", "description": "AI vision: person in formal outfit...", "meta": {"width": "640", "height": "640"} }

# ─── Python ──────────────────────────────
pip install searchx

from searchx import SearchX

sx = SearchX(api_key="sk-sx-YOUR_KEY")

# Web search
results = sx.search("kubernetes deployment", mode="hybrid")
for r in results:
    print(r.title, r.url)

# Image search
images = sx.images("sunset mountain", per_page=10)
for img in images:
    print(img.alt, img.url)

# AI answer with citations
answer = sx.answer("what is docker", include_answer=True)
print(answer.answer)

# Extract page content
page = sx.extract("https://example.com")
print(page.content)

# Free signup (no dashboard needed)
sx = SearchX.from_free_signup("you@example.com")


# ─── Node.js / TypeScript ────────────────
npm install searchx

import { SearchX } from 'searchx'

const sx = new SearchX({ apiKey: 'sk-sx-YOUR_KEY' })

// Web search
const results = await sx.search('kubernetes deployment')
results.results.forEach(r => console.log(r.title, r.url))

// Image search
const images = await sx.images('sunset mountain', { perPage: 10 })
images.results.forEach(img => console.log(img.alt, img.url))

// AI answer
const answer = await sx.answer('what is docker')
console.log(answer.answer)

// Extract
const page = await sx.extract('https://example.com')
console.log(page.content)

Endpoint:  GET https://searchx.dev/api/v1/answer
Scope:     search:agent

Parameters:
  q                string   required   Question or query
  max_results      int      5          Number of sources (1-10)
  snippet_length   int      300        Content per result (1-1000)
  include_answer   bool     false      true → LLM synthesis
  lang             string              Language filter
  safe_search      bool     true       Pass "false" to disable

# Example:
curl -G "https://searchx.dev/api/v1/answer" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=what is docker" \
  --data-urlencode "include_answer=true" \
  --data-urlencode "max_results=2"

# Real response:
{
  "query": "what is docker",
  "answer": "Docker is an open platform for developing, shipping, and running applications that enables you to separate your applications from your infrastructure [1]. It is a tool for developing, deploying, and running applications in containers, facilitating isolation and efficient resource use [2].",
  "results": [
    {
      "url": "https://docs.docker.com/get-started/docker-overview/",
      "title": "What is Docker? | Docker Docs",
      "domain": "docs.docker.com",
      "content": "Docker is an open platform for developing, shipping, and running applications...",
      "score": 800
    },
    {
      "url": "https://www.byteplus.com/en/what-is/docker",
      "title": "What is Docker?",
      "domain": "byteplus.com",
      "content": "Docker is a tool for developing, deploying, and running applications in containers...",
      "score": 332.5
    }
  ],
  "took_ms": 8090
}

Endpoint:  GET/POST https://searchx.dev/api/v1/extract
Scope:     search:read

Parameters:
  url          string   required   URL to fetch (HTML or PDF)
  render       string              "js" → headless Chromium, "static" → HTTP only
  max_length   int      50000      Max content bytes (up to 500000)
  format       string   "rich"     "rich" | "markdown" | "text"
  enrich       bool     false      AI summary + key facts + entities

Chunking (for large documents — PDFs, legal codes, books):
  chunked      bool     false      Split into navigable chunks
  chunk_size   int      6000       Target chunk size in characters
  chunk_index  int                 Read specific chunk (0-based)
  no_content   bool     false      Return only outline + metadata (no text)

# Basic extract:
curl -G "$BASE/api/v1/extract" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "url=https://example.com"

# JS-rendered (React/Vue SPAs):
curl -G "$BASE/api/v1/extract" \
  --data-urlencode "url=https://react.dev" \
  --data-urlencode "render=js"

# PDF extract:
curl -G "$BASE/api/v1/extract" \
  --data-urlencode "url=https://example.com/document.pdf"

# Chunked — get table of contents (no content):
curl -G "$BASE/api/v1/extract" \
  --data-urlencode "url=https://lex.uz/uz/docs/-6445145" \
  --data-urlencode "chunked=true" \
  --data-urlencode "no_content=true"
# → { total_chunks: 28, outline: [...], chunks: [{index, title, word_count}...] }

# Chunked — read specific chunk:
curl -G "$BASE/api/v1/extract" \
  --data-urlencode "url=https://lex.uz/uz/docs/-6445145" \
  --data-urlencode "chunked=true" \
  --data-urlencode "chunk_index=4"
# → { chunk: {title, markdown, word_count}, has_more: true }

# Response (rich format):
{
  "url": "...", "title": "...", "domain": "...",
  "markdown": "# Title\n\nClean content...",
  "word_count": 1234, "reading_time_sec": 320,
  "outline": [{"level": 1, "text": "Section"}],
  "images": ["..."], "links": ["..."],
  "quality_score": 0.85,
  "items": [{"name":"...","price":"..."}]  // auto-detected lists
}

Endpoint:  GET/POST https://searchx.dev/api/v1/web_lookup

Parameters:
  query      string   required   Search query
  find       string              Term to find in pages (word-boundary match, defaults to query)
  top_k      int      3          URLs to fetch in parallel (1-5)
  per_page   int      5          Search results to consider

# Find specific legal article:
curl "$BASE/api/v1/web_lookup?query=O'zbekiston+konstitutsiyasi+4-modda&find=4-modda"

# Research a topic:
curl -X POST "$BASE/api/v1/web_lookup" \
  -H "Content-Type: application/json" \
  -d '{"query":"kubernetes HPA autoscaling","find":"HPA","top_k":3}'

# Response:
{
  "query": "...",
  "find": "4-modda",
  "took_ms": 8500,
  "results": [
    {
      "url": "https://lex.uz/.../konstitutsiya",
      "title": "O'zbekiston Respublikasi Konstitutsiyasi",
      "matched_chunks": [
        {
          "index": 1,
          "title": "I bob. Davlat suvereniteti",
          "markdown": "4-modda. O'zbekiston Respublikasining davlat tili...",
          "word_count": 350
        }
      ],
      "total_chunks": 49
    }
  ]
}

Why use this instead of search + extract:
  - 1 API call vs 4+ calls (search → pick URL → extract → find)
  - Parallel fetch (3x faster than sequential)
  - Word-boundary match: "4-modda" won't match "14-modda" or "24-modda"
  - Returns only relevant chunks, not full 200KB pages

# 1. Create box:
curl -X POST "$BASE/api/v1/search/box" \
  -H "Content-Type: application/json" \
  -d '{"query":"python developer","category":"jobs","params":{"location":"remote"}}'
# → {"box_id":"box_abc","status":"searching","sources_total":3}

# 2. Poll (every 2s):
curl "$BASE/api/v1/search/box/box_abc?since=0"
# → {"status":"searching","total":5,"progress":33%,"results":[...]}

curl "$BASE/api/v1/search/box/box_abc?since=5"
# → {"status":"completed","total":20,"progress":100%,"results":[...]}

# 3. Or stream via SSE:
curl -N "$BASE/api/v1/search/box/box_abc/stream"
# event: result
# data: {"title":"Senior Developer","url":"...","domain":"remotive.com"}
#
# event: result
# data: {"title":"Python Engineer","url":"...","domain":"greenhouse.io"}
#
# event: done
# data: {"total":20,"elapsed_ms":3500}

# 4. Cleanup (auto-expires in 10 min):
curl -X DELETE "$BASE/api/v1/search/box/box_abc"

Endpoint:  GET https://searchx.dev/api/v1/suggest
Scope:     search:suggest (or search:read)

Parameters:
  q      string   required   Partial query (min 2 chars)
  limit  int      8          Max suggestions (1-20)

# Example:
curl -G "https://searchx.dev/api/v1/suggest" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "q=kuber" \
  --data-urlencode "limit=5"

# Real response:
{
  "suggestions": [
    "Kubernetes Monitoring",
    "Kubernetes | Drupal Europe",
    "Kubernetes Volumes: PV, PVC, and StorageClass",
    "Install Grafana Alloy on Kubernetes",
    "Kubernetes Deployment Best Practices"
  ]
}

Endpoint:  POST https://mcp.searchx.dev/mcp
Transport: Streamable HTTP (JSON-RPC 2.0)
Health:    GET  https://mcp.searchx.dev/mcp/health

Tools: search | answer | extract | suggest

# List all tools
curl -X POST "https://mcp.searchx.dev/mcp" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# ─── search tool ──────────────────────────
# Arguments: query (required), mode, page, per_page (max 20), language
curl -X POST "https://mcp.searchx.dev/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {
        "query": "kubernetes",
        "mode": "hybrid",
        "per_page": 10,
        "language": "en"
      }
    }
  }'

# ─── answer tool ──────────────────────────
# Arguments: query (required), max_results (1-10), include_answer (default true), language
curl -X POST "https://mcp.searchx.dev/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "answer",
      "arguments": {
        "query": "what is kubernetes",
        "max_results": 5,
        "include_answer": true
      }
    }
  }'

# ─── extract tool ─────────────────────────
# Arguments: url (required), max_length (max 50000)
curl -X POST "https://mcp.searchx.dev/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "extract",
      "arguments": {
        "url": "https://kubernetes.io/docs",
        "max_length": 10000
      }
    }
  }'

# ─── suggest tool ─────────────────────────
# Arguments: query (required, min 2 chars), limit (1-20)
curl -X POST "https://mcp.searchx.dev/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "suggest",
      "arguments": {
        "query": "kuber",
        "limit": 8
      }
    }
  }'

# ─── Claude Desktop config ────────────────
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "searchx": {
      "url": "https://mcp.searchx.dev/mcp",
      "transport": "http",
      "auth": {
        "type": "oauth2",
        "token_url": "https://searchx.dev/oauth2/token",
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_SECRET",
        "scope": "search:read search:agent"
      }
    }
  }
}

Tier         Price    Daily      Rate/min   Scopes
─────────────────────────────────────────────────────────────────
Free         $0       3,000      60         search:read
Starter      $9       10,000     120        search:read
                                            search:semantic
                                            search:suggest
Pro          $49      100,000    300        search:read
                                            search:semantic
                                            search:suggest
                                            search:agent
Enterprise   $199     ∞          1,000      all scopes above +
                                            search:rag
                                            search:rerank

Scope → Endpoint mapping:
  search:read       →  /search, /extract
  search:suggest    →  /suggest
  search:semantic   →  /search?mode=semantic
  search:agent      →  /answer (include_answer=true synthesis)
  search:rag        →  advanced RAG pipelines (Enterprise only)
  search:rerank     →  cross-encoder reranking (Enterprise only)

# Upgrade / manage subscription:
# → https://searchx.dev/pricing

HTTP   error              When
──────────────────────────────────────────────────────
400    invalid_request    Missing/invalid parameter
401    missing_token      No Authorization header
401    invalid_token      Expired or malformed JWT
403    insufficient_scope Token lacks scope for endpoint
429    rate_limit_exceeded   Minute or daily quota hit
500    internal_error     Server-side failure

# Example: missing token
{"error": "missing_token", "message": "Bearer token required. Get one via POST /api/v1/signup"}

# Example: scope denied
{
  "error": "insufficient_scope",
  "required": "search:agent",
  "tier": "free",
  "upgrade_url": "https://searchx.dev/pricing"
}

# Example: rate limited
{"error": "rate limit exceeded"}