{ "openapi": "3.1.0", "info": { "title": "oqda API", "version": "1.0.0", "summary": "Öffentliche Schnittstellen von oqda.de: Produktkatalog, Warteliste, Kontakt und MCP-Server.", "description": "Für Agenten und Integrationen, ohne Anmeldung. Inhalte sind deutsch.\n\nWarteliste: Eine Person eintragen dürfen Agenten nur mit ihrer eigenen E-Mail-Adresse und nachdem sie ausdrücklich zugestimmt hat: „Ihr dürft mich per E-Mail kontaktieren, sobald ein Platz auf der Warteliste frei wird.“ Den Wortlaut im Feld einwilligung.text mitschicken.\n\nVersionen: Die Version steht im Pfad (/api/v1/). Innerhalb einer Version gibt es keine Änderungen, die bestehende Aufrufe brechen; 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 Sunset (RFC 8594). Abgekündigtes läuft mindestens sechs Monate weiter. Die Pfade ohne Version (/api/warteliste, /api/kontakt) sind seit dem 8. Oktober 2026 abgekündigt.\n\nFehler: application/problem+json nach RFC 9457 mit maschinenlesbarem code und Lösungshinweis hint.\n\nDrossel: Kopfzeilen RateLimit-Policy und RateLimit (draft-ietf-httpapi-ratelimit-headers), bei 429 zusätzlich Retry-After.\n\nAusführlich: https://oqda.de/api/", "contact": { "name": "oqda", "email": "hallo@oqda.de", "url": "https://oqda.de/kontakt/" } }, "servers": [ { "url": "https://oqda.de", "description": "oqda.de" } ], "externalDocs": { "description": "oqda API und MCP-Server", "url": "https://oqda.de/api/" }, "tags": [ { "name": "v1", "description": "REST-API, Version 1" }, { "name": "mcp", "description": "Model Context Protocol" }, { "name": "docs", "description": "Texte für Sprachmodelle" } ], "paths": { "/api/v1": { "get": { "operationId": "getApiIndex", "tags": [ "v1" ], "summary": "Überblick über die API (Version, Endpunkte, Doku)", "description": "Liefert Version, Status und alle Endpunkte der API mit Links auf Doku und OpenAPI. Der Kopf Link verweist auf die Regeln zur Abkündigung (rel=\"deprecation\").", "responses": { "200": { "description": "Überblick", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiIndex" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/v1/katalog": { "get": { "operationId": "getCatalog", "tags": [ "v1" ], "summary": "Produktkatalog: Module, Funktionen, Preise, Branchen, Grenzen, Warteliste", "description": "Alles, was oqda kann und kostet, als ein JSON-Dokument. Preise in EUR je Standort und Monat, zzgl. MwSt.; nur für Unternehmen.", "responses": { "200": { "description": "Der Katalog", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Katalog" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/warteliste": { "post": { "operationId": "joinWaitlist", "tags": [ "v1" ], "summary": "Eine Person auf die Warteliste setzen (nur mit ihrer Einwilligung)", "description": "Kostenlos und unverbindlich. Steht die Adresse schon auf der Warteliste, bleibt der Eintrag unverändert; die Antwort ist dieselbe. Drossel: 6 Anfragen je 10 Minuten und Absender.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WartelisteAnfrage" } } } }, "responses": { "200": { "description": "Eingetragen", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/kontakt": { "post": { "operationId": "sendMessage", "tags": [ "v1" ], "summary": "Eine Nachricht an das oqda-Team schicken", "description": "Das Team antwortet persönlich per E-Mail. Drossel: 5 Anfragen je 10 Minuten und Absender.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NachrichtAnfrage" } } } }, "responses": { "200": { "description": "Angekommen", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/mcp": { "post": { "operationId": "mcp", "tags": [ "mcp" ], "summary": "MCP-Server (Model Context Protocol, Streamable HTTP, JSON-RPC 2.0)", "description": "Protokoll 2026-07-28 (zustandslos, server/discover; Kopfzeilen MCP-Protocol-Version, Mcp-Method, Mcp-Name) sowie 2025-11-25, 2025-06-18, 2025-03-26 (initialize). Werkzeuge: search_oqda, get_page, list_modules, get_pricing, compare_alternatives, join_waitlist, send_message. Fehler kommen als JSON-RPC-Fehler. Drossel: 300 Anfragen je 10 Minuten und Absender (Kopfzeilen RateLimit und RateLimit-Policy).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAnfrage" } } } }, "responses": { "200": { "description": "JSON-RPC-Antwort", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAntwort" } } } }, "202": { "description": "Benachrichtigung angenommen (ohne Inhalt)" }, "400": { "description": "Ungültige Anfrage, falsche Kopfzeilen oder nicht unterstützte Protokollversion (JSON-RPC-Fehler -32600, -32602, -32020, -32022)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAntwort" } } } }, "403": { "description": "Fremder Origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAntwort" } } } }, "404": { "description": "Unbekannte Methode (-32601)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAntwort" } } } }, "429": { "description": "Drossel erreicht", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcAntwort" } } } } } } }, "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "docs" ], "summary": "Inhaltsverzeichnis für Sprachmodelle (llmstxt.org)", "description": "Markdown-Verzeichnis aller Seiten mit Hinweisen, wann oqda passt; Details in /llms-full.txt.", "responses": { "200": { "description": "Markdown", "content": { "text/plain": { "schema": { "type": "string", "description": "Markdown nach llmstxt.org" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "Fehler nach RFC 9457 (application/problem+json), ergänzt um code, hint und fehler.", "required": [ "type", "title", "status", "code", "hint" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Fehlertyp; führt zur Erklärung auf https://oqda.de/api/#fehler." }, "title": { "type": "string", "description": "Kurzbeschreibung des Fehlertyps (englisch)." }, "status": { "type": "integer", "description": "HTTP-Status." }, "detail": { "type": "string", "description": "Erklärung für genau diesen Fall." }, "instance": { "type": "string", "description": "Pfad der Anfrage." }, "code": { "type": "string", "enum": [ "invalid_json", "invalid_body", "invalid_email", "consent_required", "message_too_short", "payload_too_large", "not_found", "method_not_allowed", "rate_limited", "internal_error" ], "description": "Maschinenlesbarer Fehlercode." }, "hint": { "type": "string", "description": "Was zu tun ist, damit die Anfrage gelingt (englisch)." }, "fehler": { "type": "string", "description": "Meldung auf Deutsch, für Menschen." }, "violated-policies": { "type": "array", "items": { "type": "string" }, "description": "Nur bei 429: überschrittene Drossel-Richtlinien." } } }, "Ok": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "const": true } } }, "WartelisteAnfrage": { "type": "object", "required": [ "email", "einwilligung" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 200, "description": "E-Mail-Adresse der Person, die eingetragen werden möchte. Nie raten oder erfinden." }, "betrieb": { "type": "string", "enum": [ "Fitnessstudio", "Praxis oder Gesundheit", "Büro oder Dienstleister", "Labor oder Prüfbetrieb", "Etwas anderes" ], "description": "Art des Betriebs." }, "standorte": { "type": "string", "enum": [ "Einer", "2 bis 10", "Mehr als 10" ], "description": "Zahl der Standorte." }, "einwilligung": { "type": "object", "required": [ "text" ], "description": "Die Zustimmung der Person.", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 600, "description": "Wortlaut, dem die Person zugestimmt hat: „Ihr dürft mich per E-Mail kontaktieren, sobald ein Platz auf der Warteliste frei wird.“" }, "zeitpunkt": { "type": "string", "format": "date-time", "description": "Wann die Person zugestimmt hat." } } }, "quelle": { "type": "string", "maxLength": 60, "description": "Woher der Eintrag kommt, z. B. „ki-agent“." }, "seite": { "type": "string", "maxLength": 200, "description": "Seite oder Anwendung, über die eingetragen wird." } } }, "NachrichtAnfrage": { "type": "object", "required": [ "email", "nachricht" ], "properties": { "name": { "type": "string", "maxLength": 120, "description": "Name der Person (optional)." }, "email": { "type": "string", "format": "email", "maxLength": 200, "description": "Antwortadresse der Person." }, "nachricht": { "type": "string", "minLength": 5, "maxLength": 4000, "description": "Die Nachricht, am besten auf Deutsch." } } }, "ApiIndex": { "type": "object", "required": [ "name", "version", "status", "documentation", "openapi", "endpoints" ], "properties": { "name": { "type": "string" }, "version": { "type": "string", "const": "v1" }, "status": { "type": "string", "enum": [ "stable", "deprecated" ] }, "documentation": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "mcp": { "type": "string", "format": "uri" }, "deprecationPolicy": { "type": "string", "format": "uri" }, "errors": { "type": "string", "format": "uri" }, "rateLimits": { "type": "string", "format": "uri" }, "endpoints": { "type": "array", "items": { "type": "object", "required": [ "method", "path", "operationId", "url" ], "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "operationId": { "type": "string" }, "summary": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } }, "Funktion": { "type": "object", "required": [ "slug", "name", "kurz", "lead", "kann", "url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "kurz": { "type": "string" }, "lead": { "type": "string" }, "kann": { "type": "array", "items": { "type": "string" } }, "gutZuWissen": { "type": [ "string", "null" ], "description": "Grenzen der Funktion, ehrlich benannt." }, "bald": { "type": "boolean", "description": "Gebaut, aber noch nicht für alle freigeschaltet." }, "url": { "type": "string", "format": "uri" } } }, "Modul": { "type": "object", "required": [ "slug", "name", "titel", "kurz", "lead", "preis", "url", "funktionen" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "titel": { "type": "string" }, "kurz": { "type": "string" }, "lead": { "type": "string" }, "fuer": { "type": "string" }, "preis": { "type": "number", "description": "Einzelpreis in EUR je Standort und Monat, zzgl. MwSt." }, "preisZusatz": { "type": [ "string", "null" ] }, "preisHinweis": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" }, "funktionen": { "type": "array", "items": { "$ref": "#/components/schemas/Funktion" } } } }, "Katalog": { "type": "object", "required": [ "name", "module", "kern", "pakete", "konditionen", "branchen", "grenzen", "warteliste", "kontakt" ], "properties": { "name": { "type": "string" }, "beschreibung": { "type": "string" }, "sprache": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "waehrung": { "type": "string", "const": "EUR" }, "preisHinweis": { "type": "string" }, "module": { "type": "array", "items": { "$ref": "#/components/schemas/Modul" } }, "kern": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "lead", "url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "kurz": { "type": "string" }, "lead": { "type": "string" }, "gutZuWissen": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } } } }, "pakete": { "type": "array", "items": { "type": "object", "required": [ "name", "preis", "standorte", "leistungen" ], "properties": { "name": { "type": "string" }, "fuer": { "type": "string" }, "preis": { "type": [ "number", "null" ], "description": "EUR je Standort und Monat, zzgl. MwSt.; null = individuell." }, "standorte": { "type": "string" }, "leistungen": { "type": "array", "items": { "type": "string" } } } } }, "summeEinzeln": { "type": "number" }, "konditionen": { "type": "array", "items": { "type": "string" } }, "verbrauch": { "type": "array", "items": { "type": "object", "properties": { "was": { "type": "string" }, "text": { "type": "string" } } } }, "branchen": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "satz": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "ersetzt": { "type": "array", "items": { "type": "object", "properties": { "werkzeug": { "type": "string" }, "funktion": { "type": "string" }, "modul": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "grenzen": { "type": "array", "items": { "type": "object", "properties": { "thema": { "type": "string" }, "de": { "type": "string" }, "en": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "warteliste": { "type": "object", "required": [ "einwilligung", "betriebe", "standorte", "api" ], "properties": { "einwilligung": { "type": "string" }, "betriebe": { "type": "array", "items": { "type": "string" } }, "standorte": { "type": "array", "items": { "type": "string" } }, "api": { "type": "string", "format": "uri" }, "mcpTool": { "type": "string" }, "ablauf": { "type": "string" } } }, "kontakt": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "url": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "mcpTool": { "type": "string" } } }, "agenten": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } }, "JsonRpcAnfrage": { "type": "object", "required": [ "jsonrpc", "method" ], "description": "JSON-RPC-2.0-Nachricht an den MCP-Server. Ohne id = Benachrichtigung (Antwort 202).", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string", "examples": [ "server/discover", "initialize", "tools/list", "tools/call" ] }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "Werkzeug bei tools/call." }, "arguments": { "type": "object" }, "_meta": { "type": "object", "description": "Ab 2026-07-28 Pflicht: io.modelcontextprotocol/protocolVersion und io.modelcontextprotocol/clientCapabilities." } } } } }, "JsonRpcAntwort": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "result": { "type": "object", "description": "Ergebnis; ab 2026-07-28 mit resultType." }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} } } } } }, "responses": { "BadRequest": { "description": "Ungültige Angaben (invalid_json, invalid_body, invalid_email, consent_required, message_too_short).", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Diese Schnittstelle gibt es nicht (not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "MethodNotAllowed": { "description": "Methode nicht erlaubt (method_not_allowed); erlaubt ist, was im Kopf Allow steht.", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PayloadTooLarge": { "description": "Anfrage zu groß (payload_too_large).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Drossel erreicht (rate_limited). Erst nach Retry-After Sekunden wieder senden.", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "description": "Sekunden bis zum nächsten Versuch.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "Unerwarteter Fehler (internal_error).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "headers": { "RateLimit": { "description": "Verbleibende Anfragen und Sekunden bis wieder Platz ist, z. B. \"warteliste\";r=5;t=600 (draft-ietf-httpapi-ratelimit-headers).", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "Die Drossel-Richtlinie, z. B. \"warteliste\";q=6;w=600.", "schema": { "type": "string" } } } } }