Such-API

Die Schnittstelle ist öffentlich und lesend, ohne Schlüssel. Durchsucht werden nur Websites, deren Besitzer sie bei GemeinsamKI Suche angemeldet und bestätigt haben. Solange der Index leer ist, antwortet /api/v1/search mit 503 index_not_ready.

GET /api/v1/search

Parameter	Bedeutung
`q`	Suchanfrage, höchstens 400 Zeichen (Pflicht). Alle Wörter müssen vorkommen, das letzte auch als Wortanfang; Umlaute und Akzente sind egal. `site:example.de` in der Anfrage begrenzt auf eine Website.
`page`	Ergebnisseite 1–10 zu je 10 Treffern (Standard 1)
`site`	wie `site:` in der Anfrage

Antwort 200:

{
  "query": "bäckerei weiden", "altered_query": "", "page": 1, "market": "de-de", "site": "",
  "total": 14,
  "results": [
    {
      "title": "…", "url": "https://…", "snippet": "…", "date": "2026-10-18",
      "summary": "…", "summary_kind": "auszug | ki", "extra_snippets": ["…"],
      "verified": { "verifytrust": { "id": "6f82492c-…", "name": "…", "score": "10.0", "profile": "https://verifytrust.ai/verify/…" } },
      "images": { "logo": "https://search.gemeinsamki.de/b/b-….png", "header": "https://search.gemeinsamki.de/b/b-….jpg" }
    }
  ],
  "index": { "state": "live", "documents": 22 }
}

verified ist null, wenn es zur Website kein verifiziertes VerifyTrust-Profil gibt. images fehlt, solange die Besitzer kein Logo oder Headerbild hinterlegt haben oder es noch nicht freigegeben ist; Logo als PNG (bis 512 Pixel), Headerbild als JPEG (bis 1600 Pixel breit, gedacht für einen Ausschnitt 3 : 1). Die Bilder dürfen nur zusammen mit dem Treffer der jeweiligen Website gezeigt werden; sie können jederzeit wegfallen (Zwischenspeicher höchstens eine Stunde). Rangfolge: Treffer im Titel vor Beschreibung, Überschriften, Zusammenfassung und Text (BM25); verifizierte Unternehmen und Startseiten leicht bevorzugt.

Fehler: 400 missing_query, 400 query_too_long, 429 rate_limited (Schutzgrenze je IP), 503 index_not_ready.

GET /api/v1/status

Stand des Dienstes: Version, index (aufbau | live), Zahl der Seiten im Index, der bestätigten Properties, Nachweise und Sitemaps.

Beispiel

curl -s "https://search.gemeinsamki.de/api/v1/search?q=gemeinsamki"
curl -s "https://search.gemeinsamki.de/api/v1/search?q=datenschutz&site=gemeinsamki.de&page=2"
curl -s "https://search.gemeinsamki.de/api/v1/status"

Suchanfragen zählen anonym in der Statistik (je Tag zusammengefasst, ohne IP-Adresse); das Betriebsprotokoll enthält nur den Pfad, nicht die Anfrage. Lizenz, Grenzen je Client und Schlüssel folgen.