🧭 EkkoSearch API

Metasuche · Version 0.1.0-dev · ritter-systems.de · Stand 03.09.2026

Ăśberblick

Die EkkoSearch-API ist eine Meta-Suchmaschine: Eine Abfrage wird parallel an mehrere Suchquellen geschickt, die Ergebnisse zusammengefĂĽhrt, doppelt gefundene Treffer dedupliziert und mit Quellen-Badges versehen zurĂĽckgegeben.

Authentifizierung

Drei Varianten (in dieser Reihenfolge geprĂĽft):

1. Authorization: Bearer <JWT>

JWT vom zentralen Login (POST /api/auth/login.php mit {"email": "...", "password": "..."}, Feld token). GĂĽltigkeit 24 h.

2. Authorization: Bearer <Session-Token>

Session-Token aus der bestehenden users/sessions-Datenbank (OneBluDatabase-System, z. B. vom Notizzettel).

3. X-API-Key: <Key>

Bestehender API-Key aus der api_keys-Tabelle (z. B. Notizzettel-API-Key). Praktisch fĂĽr dauerhafte Skripte ohne JWT-Ablauf.

Gast-Zugang (ohne Login)

Rolle "guest" - automatische IP-Erkennung

Ohne Login/API-Key wird die Anfrage als Gast behandelt: die kostenlose Funktion ist nutzbar (10 Suchen/Monat, nach IP), die Nutzung wird IP-basiert protokolliert. Bei Ăśberschreitung antwortet die API mit 402 QUOTA_EXCEEDED, einem freundlichen Hinweis und Verweis auf die Pricing-Seite (upgrade_url, register_url im Fehler-Body).

Datenschutz: Bei Gästen werden IP + Suchbegriff protokolliert (Zweck: Quota-Missbrauchsschutz). Bei Login-Nutzern wird stattdessen die E-Mail verknüpft.

Endpunkte

GET /ekkosearch/api/search.php?q=...
ParameterTypPflichtBeschreibung
qstringjaSuchbegriff, max. 300 Zeichen
max_resultsint 1-25nein (Default 20)Anzahl zurĂĽckgegebener (deduplizierter) Treffer
offsetint ≥ 0nein (Default 0)Startposition im Ergebnis-Pool (für "Suche fortsetzen"/Blättern)

Alternativ per POST mit JSON-Body: {"query": "...", "max_results": 20, "offset": 20}

Pagination: Der Ergebnis-Pool einer Abfrage wird serverseitig 15 Minuten gecacht. Identische Abfragen (auch mit offset) liefern in diesem Zeitfenster stabile Seiten, und das Blättern verbraucht keine Suche im Kontingent (zählt nur die erste Abfrage/das Ablaufen des Caches). Antwortfelder: total_merged (Pool-Größe), offset, returned, has_more, next_offset.
GET /ekkosearch/api/usage.php

Nutzungsstand des aktuellen Monats (zählt nicht als Suche). Ohne Login: Gast-Verbrauch der eigenen IP (plan: "guest").

Beispiel

# 1) Login (JWT holen)
curl -s -X POST https://dev-test.ritter-systems.de/api/auth/login.php \
  -H "Content-Type: application/json" \
  -d '{"email":"du@example.com","password":"..."}'

# 2) Suchen
curl -s "https://dev-test.ritter-systems.de/ekkosearch/api/search.php?q=berlin&max_results=5" \
  -H "Authorization: Bearer $TOKEN"

# ... oder mit API-Key (ohne Ablaufdatum):
curl -s "https://dev-test.ritter-systems.de/ekkosearch/api/search.php?q=berlin" \
  -H "X-API-Key: notiz_xxx..."

Antwort (Suche)

{
  "success": true,
  "query": "berlin",
  "total_results": 20,
  "total_merged": 47,
  "offset": 0,
  "returned": 20,
  "has_more": true,
  "next_offset": 20,
  "results": [
    {
      "title": "Berlin - Wikipedia",
      "url": "https://de.wikipedia.org/wiki/Berlin",
      "snippet": "Berlin ist die Hauptstadt ...",
      "sources": ["tavily", "mwmbl"]
    }
  ],
  "sources_used": ["tavily", "mwmbl"],
  "source_errors": {"marginalia": "marginalia HTTP 429 ..."},
  "usage": {
    "month": "2026-09",
    "used": 3,
    "limit": 100,
    "remaining": 97
  },
  "meta": {
    "api": "ekkosearch",
    "version": "0.1.0-dev",
    "auth_via": "jwt",
    "timestamp": "2026-09-03T08:00:00+00:00"
  }
}

Fehlercodes

HTTPCodeBedeutung
400MISSING_QUERYParameter q fehlt
400QUERY_TOO_LONGSuchbegriff > 300 Zeichen
401UNAUTHENTICATEDUngĂĽltiger Token/API-Key (gĂĽltig ist: neu einloggen, anderen Key nutzen oder als Gast suchen)
402QUOTA_EXCEEDEDLimit erreicht - Gast: 10/Monat (nach IP), Free: 100/Monat. Abo-Pläne (EkkoSearch-Abo, Premium-Overall-Abo) sind unbegrenzt. Body enthält usage, role, upgrade_url, register_url
502SOURCES_FAILEDAlle Suchquellen nicht erreichbar (Zähler wird dann nicht erhöht)

Preismodell

PlanSuchen/MonatPreisBedingung
Gast (ohne Login)100 €kein Login nötig, Tracking nach IP, freundliche Blockierung bei Überschreitung
Free1000 €ritter-systems.de-Login (Standard)
EkkoSearch-Abounbegrenzt2,99 €/MonatProjekt-Level user_project_levels(project='ekkosearch') ≥ 20 (projektbezogen)
Premium-Overall-Abounbegrenzt20 €/Monatalle Dienste von ritter-systems.de ohne Beschränkung (project='overall' ≥ 20 oder Legacy role_level ≥ 20)

Projekt-Trennung (07.09.2026): Tabelle user_project_levels (user_email, project, level) steuert je Projekt: 10=free · 20=Premium (nur dieses Projekt) · 50=Premium-Overall (alle Projekte) · 100=Admin. Wirksam wird der höchste Wert aus Projekt-Eintrag, Overall-Eintrag und Legacy role_level. Ohne Login gilt der Gast-Status (IP-basiert).

Zählung: UTC-Kalendermonat, pro erfolgreicher API-Suche (auch 0 Treffer). Fehlschläge (502) werden nicht gezählt. Das Zählerblatt liegt in der bestehenden Datenbank (search_usage, search_log).

Grenzen & Fair-Use

Changelog

Impressum · Kontakt · Pricing · Datenschutz