Overview

rsearch is a multi-source search aggregator. It queries multiple independent search providers in adaptive priority order and returns the first successful result set. Provider ordering is determined by a score combining success rate (70%) and response speed (30%).

Web Interface

The root endpoint / serves a backend-rendered HTML page. When no query is provided, a landing page with a search form is shown. When a query is submitted, results are displayed in a structured format with title, URL, description, and optional content preview.

GET Parameters

Example URLs

AI Mode

When ai=true, the system operates differently:

• The search input becomes a textarea for longer prompts.
• The prompt is sent to an AI model with two tools available:
• web_search — The AI autonomously decides whether to search the web. When it determines external information is needed, it calls web_search with an optimized query. The search executes against the same providers, fetches page content, and returns results to the AI as context. The AI may call web_search multiple times with different queries in a single conversation.
• describe_images — When the prompt contains image URLs or asks about images, the AI calls this tool. Each image URL is sent to a vision model for description. The descriptions are returned to the AI for incorporation into the final answer.
• If the AI can answer from its training data without searching, it responds directly without tool calls.
• The AI response is displayed between the search form and any search results.
• AI responses are not cached (each request produces a fresh response).

Example with curl:

curl "https://rsearch.app.molodetz.nl/?query=What+is+the+capital+of+France%3F&ai=true"

JSON API

GET /search returns JSON and supports all the same parameters as the web interface: query, count, content, cache, and ai. The behavior is identical. Response format:

{
  "query": "search terms",
  "source": "provider_name",
  "count": 10,
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "description": "Result description",
      "source": "provider_name",
      "extra": {},
      "content": "Full page content (when content=true)"
    }
  ],
  "ai_response": "AI answer (when ai=true, null otherwise)",
  "ai_error": null,
  "timestamp": "2026-01-01T00:00:00Z",
  "success": true,
  "error": null
}

When ai=true, the ai_response and ai_error fields are included. If the AI answered without searching, source is "ai" and results is empty. Cache bypass (cache=false) applies to search and content caches identically to the web interface.

Chat Endpoint

The /chat endpoint provides direct access to the configured AI model for chat completions without search integration. Responses are cached for 2 weeks by default. Supports both GET and POST methods. Outer markdown code fences are always stripped from responses automatically.

Configuration

Parameters

GET /chat

Pass parameters as query string values.

curl "https://rsearch.app.molodetz.nl/chat?prompt=What+is+the+capital+of+France%3F"

curl "https://rsearch.app.molodetz.nl/chat?prompt=List+three+programming+languages&json=true"

curl "https://rsearch.app.molodetz.nl/chat?prompt=Hello&cache=false"

curl "https://rsearch.app.molodetz.nl/chat?prompt=Translate+hello+to+French&system=You+are+a+translator"

POST /chat

Send parameters as form data or JSON body.

curl -X POST https://rsearch.app.molodetz.nl/chat -d "prompt=What is the capital of France?"

curl -X POST https://rsearch.app.molodetz.nl/chat -H "Content-Type: application/json" \
  -d '{"prompt": "List three colors", "json": true}'

curl -X POST https://rsearch.app.molodetz.nl/chat -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize quantum computing", "system": "You are a physics professor. Explain concepts clearly."}'

Response Format

{
  "response": "The capital of France is Paris.",
  "prompt": "What is the capital of France?",
  "json_mode": false,
  "max_context_window": "(dynamic, based on model)",
  "max_output_tokens": "(dynamic, context minus prompt)",
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 12,
    "total_tokens": 54,
    "cost_usd": 0.0
  },
  "elapsed": 1.2345,
  "cached": false,
  "timestamp": "2026-01-01T00:00:00Z",
  "error": null
}

Outer markdown code fences are always stripped from responses. When json=true, the response field contains raw JSON (as a string) and the model is additionally instructed to produce valid JSON only. When served from cache, cached is true and token usage reflects the original call. The system parameter is part of the cache key, so different system messages produce separate cache entries.

Image Description Endpoint

The /describe endpoint accepts images for AI vision analysis. Three methods are supported:

GET /describe?url=...

Describe an image by URL. The image is fetched by the vision model directly.

curl "https://rsearch.app.molodetz.nl/describe?url=https://en.wikipedia.org/static/images/project-logos/enwiki.png"

POST /describe (multipart file upload)

Upload an image file. The file is read, MIME type is auto-detected from file headers (PNG, JPEG, GIF, WebP, BMP), converted to a base64 data URI, and sent to the vision model. Maximum size: 10 MB.

curl -X POST https://rsearch.app.molodetz.nl/describe -F "file=@photo.jpg"

POST /describe (raw body)

Send raw image bytes in the request body with the appropriate Content-Type header. If Content-Type is not an image type, MIME detection runs on the raw bytes.

curl -X POST https://rsearch.app.molodetz.nl/describe -H "Content-Type: image/png" --data-binary @photo.png

Response format (all methods):

{
  "description": "A detailed description of the image...",
  "mime_type": "image/png",
  "size": 12345,
  "elapsed": 2.1234,
  "timestamp": "2026-01-01T00:00:00Z"
}

Results are cached for 7 days by content hash (uploaded data) or URL. Auto-detected MIME types: PNG, JPEG, GIF, WebP, BMP.

Health Endpoint

GET /health returns JSON with service status, provider ordering by score, per-provider statistics (success rate, average response time), and cache entry counts.

Caching

All cache layers are filesystem-based under ~/.cache/rsearch/ and shared across all workers:

• Page cache (6-hour TTL) — fully rendered HTML responses. Directory: pages/
• Search cache (5-minute TTL) — raw search provider results as JSON. Directory: search/
• Content cache (24-hour TTL) — fetched page content by URL hash. Directory: content/
• Vision cache (7-day TTL) — AI image description results. Directory: vision/
• Chat cache (2-week TTL) — AI chat completion responses by prompt hash. Directory: chat/

When cache=false, all layers are bypassed and fresh data is fetched. Results are still stored in cache for subsequent requests. To clear all caches: rm -rf ~/.cache/rsearch/

Scraper Information

HTML responses include structured metadata for automated consumption:

• <meta name="rsearch:*"> tags in <head> with query, source, count, response time, cache status, and timestamp.
• HTML comment block with detailed process statistics including provider ordering, cache sizes, and per-provider performance metrics.
• Each result is an <article> element with data-source, data-url, and data-content-length attributes.
• Full page content (when fetched) is present in a hidden <div class="content-full"> element within each result article.

Response Headers

Every HTTP response includes debug headers with AI token usage and cache status:

Token counts accumulate across all AI calls within a single request (chat rounds, tool calls, vision). Cache headers reflect whether any result of that type was served from cache during the request.

Error Handling

When all search providers fail, a 503 status page is returned with the message "All search providers are currently exhausted." This page is not cached. When content fetching fails for individual results, the HTTP method and status code are displayed (e.g., "Content unavailable (GET 403)").