API Reference v1

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.

REST API MCP SSE Bearer Auth JSON

Base URL

BASE_URL

https://search.iamnaime.info.bd

All API endpoints are relative to this base URL. 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.

HTTP HEADER

Authorization: Bearer YOUR_API_KEY

Two Authentication Sources

The gateway checks two sources in order: API_TOKENS env var (admin tokens, SHA-256 hashed) and api-keys.json (user-generated keys). User keys grant access to /v1/* and /mcp endpoints.

Search API

GET /v1/search

Search across 70+ engines via SearXNG with DuckDuckGo fallback.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query. URL-encoded.
`categories`	string	No	Comma-separated: `general`, `images`, `news`, `science`
`engines`	string	No	Comma-separated: `google`, `bing`, `duckduckgo`, `brave`, `wikipedia`
`language`	string	No	Format: `lang-COUNTRY`. Default: `en`
`time_range`	string	No	`day`, `week`, `month`, `year`
`safesearch`	integer	No	`0` off, `1` moderate, `2` strict. Default: `1`

Example Request

curl COPY

# 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&engines=google,bing&time_range=week"

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

Response

200 OK application/json

{
  "query": "latest AI news",
  "results": [{ "title": "...", "url": "...", "content": "..." }],
  "number_of_results": 10,
  "engine": "searxng",
  "cached": false,
  "request_id": "a1b2c3d4-..."
}

Read API

POST /v1/read

Extract clean, readable text from any URL. Uses page-reader (trafilatura) with local HTML extraction fallback.

Request Body (JSON)

Field	Type	Required	Description
`url`	string	Yes	URL to extract. Internal IPs blocked (SSRF).
`timeout`	integer	No	1-30 seconds. Default: `10`

curl COPY

$ 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"

200 OK application/json

{
  "url": "https://docs.anthropic.com",
  "title": "Anthropic Documentation",
  "text": "Extracted content...",
  "word_count": 1542,
  "method_used": "page-reader",
  "request_id": "a1b2c3d4-..."
}

Text Truncation: Responses truncated to 8,000 chars (configurable via MAX_TEXT_LENGTH).

MCP Server

SSE /mcp

Native MCP server with SSE transport. Works with Claude Code, Claude Desktop, Cursor, and any MCP client.

SSE Endpoint

GET /mcp

Messages Endpoint

POST /mcp/messages?sessionId=xxx

Available Tools

web_search SEARCH

General web search via SearXNG. Falls back to DuckDuckGo HTML on failure.

search_images IMAGES

Image search. Returns titles, URLs, thumbnails.

search_videos VIDEOS

Video search. YouTube, Vimeo, Dailymotion, and more.

search_news NEWS

News article search with time_range filtering.

search_papers SCIENCE

Academic papers from arXiv, Google Scholar, PubMed, and more.

read_page EXTRACT

Extract readable text from a URL. Max 8,000 chars.

Client Configuration

Claude Code

.claude/settings.json COPY

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

Claude Desktop

claude_desktop_config.json COPY

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

Rate Limits

Differentiated per route. Per API key (falls back to IP). Sliding window.

Route	Limit	Window
`/v1/search`	20 req	1 min
`/v1/read`	40 req	1 min
`/mcp` (all tools)	60 req	1 min
Monthly per user	43,200 req	calendar month

RATE_LIMIT_HEADERS

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

Caching

Search Cache

TTL5 min (300s)

Max1,000

Read Cache

TTL1 hour (3600s)

Max1,000

Error Format

Consistent envelope. Every response includes request_id (UUID) and X-Request-Id header.

ERROR RESPONSE

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required parameter: q",
    "details": {},
    "status": 400
  },
  "request_id": "a1b2c3d4-..."
}

Common Error Codes

Status	Code	Description
400	`VALIDATION_ERROR`	Missing or invalid parameters
401	`UNAUTHORIZED`	Missing or invalid auth header
403	`SSRF_BLOCKED`	URL targets internal IP
429	`RATE_LIMIT_EXCEEDED`	Too many requests
429	`QUOTA_EXCEEDED`	Monthly quota exceeded
500	`INTERNAL_ERROR`	Unexpected server error
502	`UPSTREAM_FAILURE`	Both fallbacks failed

Quick Start

Step 1: Get your API key

Register at search.iamnaime.info.bd with your email. Verify the 6-digit code.

Step 2: Test your key

terminal COPY

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

Step 3: Connect your AI tool

Add the MCP server to your config. See MCP Configuration above.

Step 4: Start searching

Your AI agent can now use web_search and read_page tools.