API & MCP

oqda API und MCP-Server

Für Entwickler und KI-Agenten: Inhalte von oqda lesen, Module und Preise abfragen, oqda mit einzelnen Tools vergleichen und eine Person auf die Warteliste setzen, wenn sie das möchte und zugestimmt hat. Ohne Anmeldung.

Überblick

• REST-API, Version 1: https://oqda.de/api/v1 (JSON).
• MCP-Server: https://oqda.de/mcp (Model Context Protocol).
• OpenAPI-Beschreibung (3.1) und ein API-Katalog nach RFC 9727 unter /.well-known/api-catalog.
• llms.txt, llms-full.txt und jede Seite als Markdown (Kopf Accept: text/markdown).

REST-API (Version 1)

• GET /api/v1: Überblick mit Version, Endpunkten und Links.
• GET /api/v1/katalog: Produktkatalog mit Modulen, Funktionen, Preisen, Branchen, Grenzen und den Feldern der Warteliste.
• POST /api/v1/warteliste: eine Person auf die Warteliste setzen, nur mit ihrer Einwilligung.
• POST /api/v1/kontakt: eine Nachricht an das oqda-Team; die Antwort kommt persönlich per E-Mail.

Beispiel:

curl -X POST https://oqda.de/api/v1/warteliste \
  -H 'Content-Type: application/json' \
  -d '{"email": "person@betrieb.de", "betrieb": "Fitnessstudio", "standorte": "Einer",
       "einwilligung": {"text": "Ihr dürft mich per E-Mail kontaktieren, sobald ein Platz auf der Warteliste frei wird."}}'

Antwort bei Erfolg: {"ok": true}. Alle Felder und Antworten stehen in der OpenAPI-Beschreibung.

MCP-Server

Adresse: https://oqda.de/mcp (Streamable HTTP, ohne Anmeldung). Unterstützt wird das aktuelle Protokoll 2026-07-28 (zustandslos, mit server/discover) und für ältere Clients 2025-11-25, 2025-06-18, 2025-03-26 (mit initialize).

So trägst du den Server in einem MCP-Client ein:

{
  "mcpServers": {
    "oqda": {
      "type": "http",
      "url": "https://oqda.de/mcp"
    }
  }
}

Werkzeuge:

• search_oqda: Search oqda.de. Nur lesend.
• get_page: Read a page of oqda.de. Nur lesend.
• list_modules: List oqda modules and features. Nur lesend.
• get_pricing: Get oqda pricing. Nur lesend.
• compare_alternatives: Compare oqda with separate tools. Nur lesend.
• join_waitlist: Put a person on the oqda waitlist. Schreibt einen Eintrag.
• send_message: Send a message to the oqda team. Schreibt einen Eintrag.

Personen auf die Warteliste setzen

Agenten dürfen eine Person auf die Warteliste setzen, wenn die Person das möchte. Dafür gilt:

• Nur mit der eigenen E-Mail-Adresse der Person, niemals geraten oder erfunden.
• Nur nachdem die Person diesem Wortlaut ausdrücklich zugestimmt hat: „Ihr dürft mich per E-Mail kontaktieren, sobald ein Platz auf der Warteliste frei wird.“
• Per POST /api/v1/warteliste (Wortlaut im Feld einwilligung.text) oder per MCP mit join_waitlist.
• Der Platz ist kostenlos und unverbindlich. Wird er frei, meldet sich oqda persönlich; nach dem Gespräch entscheidet der Betrieb.

Gespeichert werden E-Mail-Adresse, Art des Betriebs, Zahl der Standorte, der Wortlaut der Einwilligung mit Zeitpunkt und, falls zutreffend, dass der Eintrag über einen KI-Assistenten kam. Steht die Adresse schon auf der Warteliste, bleibt der Eintrag unverändert. Widerrufen kann die Person jederzeit formlos per E-Mail an hallo@oqda.de. Mehr in der Datenschutzerklärung.

Fehler

Fehler kommen als application/problem+json nach RFC 9457: mit maschinenlesbarem code, einem Hinweis hint, was zu tun ist, und der Meldung fehler auf Deutsch. Auch unbekannte Pfade unter /api/ antworten so, nie mit einer HTML-Seite. Beispiel:

{
  "type": "https://oqda.de/api/#fehler-consent-required",
  "title": "Consent missing",
  "status": 400,
  "detail": "Bitte die Einwilligung bestätigen.",
  "instance": "/api/v1/warteliste",
  "code": "consent_required",
  "hint": "Show the person the consent statement from /api/v1/katalog (warteliste.einwilligung) and send it in einwilligung.text once they agreed.",
  "fehler": "Bitte die Einwilligung bestätigen."
}

• invalid_json (400): Der Inhalt ist kein gültiges JSON. Send a JSON object with Content-Type: application/json.
• invalid_body (400): Der Inhalt muss ein JSON-Objekt sein. Send a JSON object, not null, an array or a string.
• invalid_email (400): Die E-Mail-Adresse fehlt oder ist ungültig. Pass the person's own e-mail address in the field "email".
• consent_required (400): Die Einwilligung der Person fehlt (einwilligung.text). Show the person the consent statement from /api/v1/katalog (warteliste.einwilligung) and send it in einwilligung.text once they agreed.
• message_too_short (400): Die Nachricht ist kürzer als 5 Zeichen. Send at least 5 characters in the field "nachricht".
• payload_too_large (413): Die Anfrage ist zu groß. Keep the JSON body under 10 kB (waitlist) or 20 kB (contact).
• not_found (404): Diesen Endpunkt gibt es nicht. See /api/v1 for the list of endpoints or /openapi.json for the full description.
• method_not_allowed (405): Diese HTTP-Methode ist hier nicht erlaubt. Use the method given in the Allow header.
• rate_limited (429): Zu viele Anfragen; die Drossel ist erreicht. Wait for the number of seconds in Retry-After and read the RateLimit header before retrying.
• internal_error (500): Unerwarteter Fehler auf unserer Seite. Try again later. If it keeps failing, write to hallo@oqda.de.

Drosselung

Jede Antwort der API nennt die Drossel in den Kopfzeilen RateLimit-Policy und RateLimit (IETF-Entwurf draft-ietf-httpapi-ratelimit-headers), zum Beispiel RateLimit: "warteliste";r=5;t=600: noch 5 Anfragen, wieder Platz in spätestens 600 Sekunden. Bei Status 429 sagt Retry-After, wie viele Sekunden zu warten sind. Gezählt wird je Absender:

• warteliste: 6 Anfragen je 10 Minuten.
• kontakt: 5 Anfragen je 10 Minuten.
• api (alle anderen Endpunkte): 300 Anfragen je 10 Minuten.
• mcp (MCP-Server): 300 Anfragen je 10 Minuten; Einträge über join_waitlist und send_message zählen zusätzlich bei warteliste und kontakt.

Versionen und Abkündigung

Die Version steht im Pfad: /api/v1/. Innerhalb einer Version ändern wir nichts, was bestehende Aufrufe bricht; neu hinzukommen höchstens optionale Felder. Wird eine Version oder ein Pfad abgekündigt, antwortet er mit dem Kopf Deprecation (RFC 9745) und einem Link rel="successor-version" auf den Nachfolger; steht ein Abschaltdatum fest, zusätzlich mit Sunset (RFC 8594). Abgekündigtes läuft mindestens sechs Monate weiter, und wir kündigen es hier an.

Abgekündigt seit dem 8. Oktober 2026: die Pfade ohne Version /api/warteliste und /api/kontakt. Nachfolger sind /api/v1/warteliste und /api/v1/kontakt; ein Abschaltdatum gibt es noch nicht. Der MCP-Server versioniert über das Protokoll selbst.

Datenschutz und Sicherheit

Die Schnittstellen geben nur heraus, was ohnehin öffentlich auf oqda.de steht. Aus der Warteliste und den Nachrichten liest keine Schnittstelle: Ob eine Adresse schon eingetragen ist, lässt sich nicht abfragen, die Antwort ist immer dieselbe. Es gibt keine Cookies und keine Anmeldung.

Kontakt

Fragen zur API: hallo@oqda.de oder über das Kontaktformular.