API Documentation

AI Search Gateway provides a unified REST API and MCP server for web search and page content extraction. SearXNG-powered with intelligent fallback chains. Self-hosted with full data control.

Base URL

https://search.iamnaime.info.bd

All API endpoints are relative to this base URL. The server uses TLS 1.3 encryption in production.

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are SHA-256 hashed. Comparison uses constant-time crypto.timingSafeEqual to prevent timing attacks.

Authorization: Bearer YOUR_API_KEY

Search API

Search the web across 70+ engines via SearXNG with DuckDuckGo fallback. Returns structured results with titles, URLs, and snippets.

Query Parameters

Example Request

# Basic search
$ curl -H "Authorization: Bearer $TOKEN" \
  "https://search.iamnaime.info.bd/v1/search?q=latest+AI+news"

# With filters
$ curl -H "Authorization: Bearer $TOKEN" \
  "https://search.iamnaime.info.bd/v1/search?q=climate+change&engines=google,bing&time_range=week&language=en-US"

# Node.js
const res = await fetch('/v1/search?q=hello+world', {
  headers: { 'Authorization': `Bearer ${TOKEN}` }
});
const data = await res.json();

Response

{
  "query": "latest AI news",
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com/article",
      "content": "Snippet text...",
      "engine": "google",
      "score": 0.95,
      "category": "general"
    }
  ],
  "number_of_results": 10,
  "engine": "searxng",
  "cached": false,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Read API

Extract clean, readable text from any URL. Uses page-reader service (trafilatura) with local HTML extraction fallback. Handles JavaScript-rendered content and complex layouts. Dual fallback chain ensures high availability.

Request Body (JSON)

$ curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://docs.anthropic.com","timeout":15}' \
  "https://search.iamnaime.info.bd/v1/read"

# Node.js
const res = await fetch('/v1/read', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com' })
});

{
  "url": "https://docs.anthropic.com",
  "title": "Anthropic Documentation",
  "text": "Extracted page content (plain text)...",
  "word_count": 1542,
  "method_used": "page-reader",
  "cached": false,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

MCP Server

Native Model Context Protocol server with SSE (Server-Sent Events) transport. Compatible with Claude Code, Claude Desktop, Cursor, and any MCP client. Provides tools for web search and page reading directly from AI agents.

Available Tools

Client Configuration

{
  "mcpServers": {
    "web-search": {
      "url": "https://search.iamnaime.info.bd/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "web-search": {
      "url": "https://search.iamnaime.info.bd/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Rate Limits

Differentiated rate limits per route. Applied per API key (falls back to IP if no key). Uses sliding window algorithm. Both REST and MCP endpoints share the same limits.

# Response includes IETF rate limit headers:
RateLimit-Limit: 20
RateLimit-Remaining: 18
RateLimit-Reset: 45
Retry-After: 12  # only on 429

Caching

LRU cache with configurable TTL. HTTP ETag support for 304 Not Modified responses.

Error Format

All errors follow a consistent envelope format. Every response includes a request_id (UUID) for debugging, also available in the X-Request-Id response header.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required parameter: q",
    "details": {},
    "status": 400
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Common Error Codes

Quick Start

Get up and running in under a minute.

$ curl -s -H "Authorization: Bearer YOUR_KEY" \
  "https://search.iamnaime.info.bd/v1/search?q=hello+world" | jq .number_of_results
10