# SearXNG-JSON-API aktivieren Von Das Digitale Momentum, veröffentlicht am 2026-11-03 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](https://docs.searxng.org/dev/search_api.html) 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](https://docs.searxng.org/admin/installation-docker.html) 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](https://docs.searxng.org/admin/settings/settings_search.html)). ``` 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](https://docs.searxng.org/dev/search_api.html)): - 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](https://docs.searxng.org/admin/searx.limiter.html), 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](https://valkey.io/)-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](https://caddyserver.com/) 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 } 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](https://www.searxncrawl.io/de/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](https://www.searxncrawl.io/de/ueber-uns/#editorial) beschreibt, wie wir sie aktuell halten und Fehler korrigieren. ## Häufige Fragen ### Ist die SearXNG-JSON-API standardmäßig aktiv? Nein. SearXNG liefert HTML, bis `json` unter `search.formats` in der `settings.yml` steht; bis dahin beantwortet es eine Anfrage mit `format=json` mit 403 Forbidden. ### Wie behebe ich 403 Forbidden bei format=json in SearXNG? Tragen Sie `json` unter `search.formats` in die `settings.yml` ein, die Ihre Instanz tatsächlich lädt (im Container `/etc/searxng/settings.yml`), starten Sie SearXNG neu und wiederholen Sie die Anfrage mit `format=json`. ### Kann ich die JSON-API einer öffentlichen SearXNG-Instanz nutzen? Selten. Die SearXNG-Dokumentation warnt, dass viele öffentliche Instanzen diese Formate abgeschaltet haben, und öffentliche Instanzen begrenzen automatisierte Anfragen. Betreiben Sie für Agenten und Skripte eine eigene Instanz. ### Braucht die SearXNG-JSON-API einen API-Key? Nein. SearXNG kennt keine API-Keys: Wer die Instanz erreicht, kann sie abfragen. Betreiben Sie sie in einem privaten Netz oder hinter einer Anmeldung; searxNcrawl kann `SEARXNG_USERNAME` und `SEARXNG_PASSWORD` oder zusätzliche Header mitsenden. Aktualisiert: 2026-11-04 --- Quelle: