SearXNG-JSON-API aktivieren

Von Das Digitale Momentum, veröffentlicht am 3. November 2026

SearXNG antwortet nur mit HTML, bis die JSON-Ausgabe aktiviert ist, und eine Anfrage mit format=json endet mit 403 Forbidden. Diese Anleitung aktiviert die JSON-API in der settings.yml, testet sie mit curl und bindet die Instanz mit searxNcrawl an KI-Agenten an.

Warum format=json 403 Forbidden liefert

SearXNG liefert ein Ergebnisformat nur, wenn die settings.yml es unter search.formats aufführt. Laut seiner Dokumentation der Such-API beantwortet es eine Anfrage nach einem nicht aktivierten Format mit 403 Forbidden, und viele öffentliche Instanzen haben diese Formate abgeschaltet. Die Lösung braucht also eine Instanz, deren Einstellungen Sie selbst verwalten.

Die HTML-Seite von SearXNG ist für Menschen im Browser gemacht. Skripte und KI-Agenten brauchen dieselben Ergebnisse als Daten: Die JSON-API liefert die zusammengeführten Treffer aller Suchmaschinen, die die Instanz abfragt, mit Quellen und Bewertung, in einer Antwort, die ein Programm ohne Scraping auswerten kann. Werkzeuge auf Basis von SearXNG, von Kommandozeilen-Clients bis zu MCP-Servern wie searxNcrawl, hängen davon ab; deshalb stoppt ein fehlender Eintrag json sie alle mit demselben 403.

Schritt 1: SearXNG starten

Wenn Sie noch keine Instanz haben, starten Sie eine im Container, wie in der Docker-Anleitung von SearXNG beschrieben. Die Instanz antwortet auf Port 8888, ihre Konfiguration in ./config/ ist im Container als /etc/searxng/ eingebunden.

docker run --name searxng -d \
  -p 8888:8080 \
  -v "./config/:/etc/searxng/" \
  -v "./data/:/var/cache/searxng/" \
  docker.io/searxng/searxng:latest

Der Schalter -d startet den Container im Hintergrund, und --name searxng gibt ihm den Namen, den der Neustart in Schritt 3 verwendet. Port 8888 auf dem Host zeigt auf Port 8080 im Container; ist 8888 belegt, wählen Sie einen anderen Host-Port und nutzen ihn in jeder Adresse auf dieser Seite. Das Verzeichnis data hält den Cache zwischen Neustarts.

Schritt 2: JSON in der settings.yml aktivieren

Öffnen Sie ./config/settings.yml und tragen Sie json unter search.formats ein, neben html für die Browser-Oberfläche. Formatnamen sind kleingeschrieben; csv und rss aktivieren Sie genauso (Referenz der Einstellungen).

search:
  formats:
    - html
    - json

Schritt 3: neu starten und testen

Starten Sie den Container neu, damit SearXNG die neuen Einstellungen liest, und fragen Sie dann JSON ab. Ein JSON-Objekt mit einem Array results heißt, die API funktioniert; 403 Forbidden heißt, die Formatliste wurde nicht übernommen.

docker restart searxng
curl -s 'http://localhost:8888/search?q=searxng&format=json' | head -c 300

Was die JSON-Antwort enthält

Die Antwort ist ein JSON-Objekt. results enthält die Treffer: jeweils mit url, title, content (dem Snippet), der Suchmaschine in engine, die ihn zuerst eingestuft hat, allen Suchmaschinen in engines, die ihn gefunden haben, einem zusammengeführten score, der category und, wo eine Suchmaschine es liefert, publishedDate. Daneben tragen answers, corrections, infoboxes und suggestions, was die Suchmaschinen über reine Links hinaus ergänzen. Auf ein Ergebnis gekürzt, sieht eine Antwort so aus:

{
  "query": "searxng",
  "results": [
    {
      "url": "https://github.com/searxng/searxng",
      "title": "...",
      "content": "...",
      "engine": "google cse",
      "engines": ["google cse", "duckduckgo"],
      "score": 3.0,
      "category": "general",
      "publishedDate": null
    }
  ],
  "answers": [],
  "corrections": [],
  "infoboxes": [],
  "suggestions": [],
  "unresponsive_engines": [["brave", "Suspended: too many requests"]]
}

unresponsive_engines nennt jede Suchmaschine, die für diese Anfrage ausgefallen ist, mit dem Grund. Vorgelagerte Suchmaschinen begrenzen oder prüfen eine neue Instanz hin und wieder; die übrigen antworten weiter, die Ergebnisse bleiben also brauchbar.

Skripte und Agenten brauchen meist nur url, title und content; die übrigen Felder helfen bei Sortierung und Fehlersuche. Ergebnisse, die mehrere Suchmaschinen gefunden haben, tragen einen höheren score, ein schnelles Zeichen dafür, worin die Suchmaschinen übereinstimmen.

Parameter der JSON-API

Sowohl / als auch /search nehmen diese Parameter an, als URL-Parameter mit GET oder als Formulardaten mit POST (Referenz der Such-API):

q

Die Suchanfrage; Pflicht

format

json, csv oder rss; jedes muss unter search.formats stehen, sonst lautet die Antwort 403

categories

Kommagetrennte Liste der zu durchsuchenden Kategorien, zum Beispiel general oder news

language

Sprachcode der Ergebnisse; der Standard kommt aus der settings.yml

pageno

Ergebnisseite, beginnend bei 1

time_range

day, month oder year

safesearch

0, 1 oder 2; der Standard kommt aus der settings.yml

Für die meisten Zwecke genügt GET: Kodieren Sie die Anfrage für die URL, hängen Sie format=json an und holen Sie die nächste Seite mit pageno=2. POST sendet dieselben Parameter als Formulardaten, sodass die Anfrage nicht in der URL steht. Sollen auch Feedreader oder Tabellen bedient werden, tragen Sie zusätzlich rss oder csv unter search.formats ein; jedes Format wird einzeln freigeschaltet, wie das 403 für csv in unserem Test zeigt.

Wenn der Test weiter fehlschlägt

• 403 Forbidden: json fehlt unter search.formats, oder die bearbeitete Datei ist nicht die, die als /etc/searxng/settings.yml eingebunden ist.
• 429 Too Many Requests: Der Limiter, aktiviert mit server.limiter, bremst verdächtige Clients. Tragen Sie die Adresse Ihres Agenten-Hosts unter pass_ip in /etc/searxng/limiter.toml ein.
• Keine Antwort aus einem anderen Container: Sprechen Sie SearXNG über den Containernamen in einem gemeinsamen Netz an, nicht über localhost.
• Eine öffentliche Instanz: Nutzen Sie eine eigene. Öffentliche Instanzen schalten JSON oft ab und begrenzen automatisierte Anfragen.

Die Instanz privat halten

Beim ersten Start schreibt der Container eine kurze settings.yml mit use_default_settings: true und einem zufälligen server.secret_key; halten Sie diesen Schlüssel geheim und lassen Sie die Datei im eingebundenen Verzeichnis, damit sie Updates des Images übersteht. SearXNG kennt keine API-Keys: Wer Port 8888 erreicht, kann Ihre Instanz und den Ruf ihrer Adresse nutzen. Binden Sie sie an localhost oder ein privates Netz, oder setzen Sie einen Reverse Proxy mit Anmeldung davor.

Teilen sich mehrere Agenten oder Menschen die Instanz, lohnt der Limiter. Er braucht eine in der settings.yml eingetragene Valkey-Datenbank und begrenzt verdächtigen Verkehr je Client-Adresse, sodass die vorgelagerten Suchmaschinen Ihre Instanz seltener sperren oder prüfen. Vertrauenswürdige Clients, etwa der Host Ihrer Agenten, gehören unter pass_ip in die limiter.toml und behalten uneingeschränkten Zugriff. Hinter einem Reverse Proxy geben Sie die Client-Adresse in X-Forwarded-For und X-Real-IP weiter; sonst sieht jede Anfrage aus, als käme sie vom Proxy.

Braucht SearXNG einen API-Key?

Nein. SearXNG kennt keine API-Keys und keine Einstellung dafür: Wer die Instanz erreicht, kann sie abfragen. In unserem Test antworteten eine Anfrage ganz ohne Key und eine mit einem erfundenen Header X-API-Key beide mit 200 und Ergebnissen. Anleitungen, die einen solchen Header nennen, beschreiben einen Proxy oder einen Wrapper vor SearXNG, nicht SearXNG selbst.

Um einzuschränken, wer suchen darf, setzen Sie einen Reverse Proxy mit Anmeldung vor die Instanz. Mit Caddy braucht das ein gemeinsames Netz, einen Passwort-Hash und eine kurze Caddyfile. Legen Sie zuerst das Netz und den Hash an:

docker network create searxng-net
docker network connect searxng-net searxng
docker run --rm caddy:2 caddy hash-password --plaintext 'choose-a-password'

Schreiben Sie den Hash in eine Datei namens Caddyfile neben dem Verzeichnis config. Der Proxy lauscht in seinem Container auf Port 8080 und leitet angemeldete Anfragen über den Containernamen an SearXNG weiter:

:8080 {
	basic_auth {
		agent <hash from caddy hash-password>
	}
	reverse_proxy searxng:8080
}

docker run --name searxng-auth -d --network searxng-net \
  -p 8889:8080 -v "./Caddyfile:/etc/caddy/Caddyfile" caddy:2
curl -s -o /dev/null -w '%{http_code}\n' -u agent:choose-a-password \
  'http://localhost:8889/search?q=searxng&format=json'

In unserem Lauf antwortete der Proxy ohne Zugangsdaten und mit falschem Passwort mit 401, mit dem richtigen mit 200. Veröffentlichen Sie danach nur noch den Proxy: Starten Sie SearXNG mit -p 127.0.0.1:8888:8080 oder ganz ohne -p, damit der Port ohne Passwort von anderen Rechnern aus nicht erreichbar ist. searxNcrawl sendet die Zugangsdaten als Basic Auth:

SEARXNG_URL=http://localhost:8889 SEARXNG_USERNAME=agent \
  SEARXNG_PASSWORD=choose-a-password uvx --from searxncrawl search "model context protocol"

Ohne die beiden Variablen schlug dieselbe Suche mit der Meldung fehl, dass die Anmeldung bei SearXNG gescheitert ist und SEARXNG_USERNAME und SEARXNG_PASSWORD zu prüfen sind; mit ihnen lieferte sie Ergebnisse. Für ein Token in einem Header, etwa das eines API-Gateways, setzen Sie stattdessen SEARXNG_EXTRA_HEADERS.

Die JSON-API an KI-Agenten anbinden

searxNcrawl ist ein quelloffener MCP-Server, der diese JSON-API nutzt: Setzen Sie SEARXNG_URL auf die Instanz, und Ihre Agenten bekommen das Tool search, dazu crawl und crawl_site für Seiteninhalte als Markdown. Probieren Sie zuerst eine Suche in der Shell:

SEARXNG_URL=http://localhost:8888 uvx --from searxncrawl search "model context protocol" --max-results 5

Führen Sie dann uvx searxncrawl setup aus, um den Server bei Claude Code, Codex, Gemini CLI, Cursor, VS Code und Claude Desktop einzutragen. Die Seite zum SearXNG-MCP-Server zeigt die Einrichtung für jeden Client.

searxNcrawl sendet bei jeder Suche format=json zusammen mit Sprache, SafeSearch und Seite; auf der Seite von SearXNG ändert sich also nur die Formatliste. Liegt die Instanz hinter Basic Auth, setzen Sie SEARXNG_USERNAME und SEARXNG_PASSWORD; für ein Token in einem Header, etwa das eines Tunnels oder Gateways, nutzen Sie SEARXNG_EXTRA_HEADERS, das den Wert auch aus einer Datei lesen kann.

So haben wir diese Anleitung getestet

Wir haben jeden Schritt am 2026-11-04 mit dem Image docker.io/searxng/searxng:latest (SearXNG 2026.9.15) und searxNcrawl 0.33.1 ausgeführt. Solange json in der Formatliste fehlte, beantwortete SearXNG format=json mit 403 Forbidden; nach dem Neustart mit 200 und 20 Ergebnissen, während format=csv, weiter nicht eingetragen, bei 403 blieb. Für den Abschnitt zu API-Keys haben wir Caddy 2.11.7 mit Basic Auth vor dieselbe Instanz gesetzt.

Wir haben diese Angaben am 2026-11-04 anhand der verlinkten Quellen geprüft. Unsere Redaktions- und Korrekturrichtlinie beschreibt, wie wir sie aktuell halten und Fehler korrigieren.

Häufige Fragen