raisearch API reference

Overview

Most of our HTTP surface is internal plumbing for the web UI. The endpoints below are what you will likely use for making external calls.

These endpoints live at the same host and port as your UI (http://localhost:4444 by default, or RAIYUN_PORT). All responses are returned in JSON. You can configure rate limits by going to Settings then Server, and these limits will apply to every caller.

API key protection (optional)

In Settings -> Server you can require authentication for search, search stream, search retry, and suggest. When that is enabled for a route, requests without valid credentials receive 401 and a JSON body such as {"error":"Unauthorized"}.

For external callers (scripts, integrations, curl, Open WebUI, etc.), use the API key from the same settings screen (the 64-character hexadecimal value) as a Bearer token. The server compares it to the stored secret; only that exact key is accepted.

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  "http://localhost:4444/api/search?q=hello"

The in-browser UI does not rely on this header; it uses a separate short-lived nonce supplied with the page when protection is on.

GET /api/search

Run a metasearch and get merged and scored results.

curl "http://localhost:4444/api/search?q=rust+lifetimes"

Response:

{
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "...",
      "source": "google",
      "score": 92,
      "sources": ["google", "duckduckgo"]
    }
  ],
  "query": "rust lifetimes",
  "totalTime": 812,
  "type": "web",
  "engineTimings": [{ "name": "Google", "time": 540, "resultCount": 10 }],
  "relatedSearches": ["rust lifetime elision", "..."]
}

POST /api/search

This works exactly like the GET version but accepts a JSON body. You should use this when you have a long list of engines to query.

curl -X POST http://localhost:4444/api/search \
-H "Content-Type: application/json" \
-d '{
  "query": "rust lifetimes",
  "type": "web",
  "page": 1,
  "lang": "en",
  "engines": ["google", "duckduckgo"]
}'

GET /api/search/stream

This is the Server Sent Events variant. It uses the exact same query parameters as GET /api/search and emits two events:

• engine-result fires as each engine returns. The results field contains the running merged list, so you can simply keep the last one if you are a lazy consumer.
• done is the final event containing totalTime, engineTimings, and relatedSearches.

curl -N "http://localhost:4444/api/search/stream?q=hello"

GET /api/suggest?q=...

Fetches autocomplete suggestions merged from Google and DuckDuckGo. This returns an array of strings.

GET /api/lucky?q=...

Runs a web search and sends a 302 redirect directly to the URL of the first result.

GET /opensearch.xml

OpenSearch descriptor that allows browsers to install Raiyun as a search engine.

Tip: wiring Raiyun into Open WebUI

Raiyun is completely SearXNG compatible for the built in web search inside Open WebUI, meaning you will not need any custom tools.

1. Open WebUI and go to your Admin Panel.
2. Navigate to Settings.
3. Select Web Search and enable it.
4. Set your Web Search Engine to searxng.
5. Set the SearxNG Query URL to your Raiyun instance URL followed by /api/search, like this: http://127.0.0.1:4444/api/search.

Just remember to replace http://127.0.0.1:4444 with your actual Raiyun address.

If you enabled API key protection for search, configure your client to send Authorization: Bearer … with your instance key as described above (Open WebUI must support custom headers for the search URL if you use that mode).