{
    "openapi": "3.1.0",
    "info": {
        "title": "SAXSOC öffentliche Auskunft",
        "version": "0.3.19",
        "description": "Öffentliche Lesefunktionen ohne API-Schlüssel. Keine Preise, Buchungen oder private Daten. NLWeb und MCP haben eigene Protokolldokumentation. Limit: 240 Anfragen je Minute, angezeigt in RateLimit-Policy/RateLimit und X-RateLimit-*, bei 429 mit Retry-After."
    },
    "servers": [
        {
            "url": "https://marjanmarkelj.de/wp-json/saxsoc/v1"
        }
    ],
    "security": [],
    "paths": {
        "/company": {
            "get": {
                "operationId": "getCompany",
                "summary": "Anbieter mit Quellen",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Company"
                                },
                                "example": {
                                    "schemaVersion": "1.0",
                                    "updatedAt": "2026-09-13T17:43:43+00:00",
                                    "sources": [
                                        {
                                            "url": "https://marjanmarkelj.de/",
                                            "title": "Marjan Markelj – Saxophone Society"
                                        },
                                        {
                                            "url": "https://marjanmarkelj.de/impressum/",
                                            "title": "Impressum und Kontakt"
                                        }
                                    ],
                                    "name": "Marjan Markelj",
                                    "brand": "Saxophone Society",
                                    "description": "Saxophon lernen mit Marjan Markelj: Online-Angebote für den deutschsprachigen Raum; lokale Angebote ergänzend.",
                                    "serviceArea": [
                                        "Deutschland",
                                        "Österreich",
                                        "Schweiz"
                                    ],
                                    "audiences": [
                                        "Academy: erwachsene Anfänger und Wiedereinsteiger",
                                        "Circle: fortgeschrittene Saxophonspieler"
                                    ],
                                    "address": {
                                        "streetAddress": "Dieselstraße 2",
                                        "postalCode": "40721",
                                        "addressLocality": "Hilden",
                                        "addressCountry": "DE"
                                    },
                                    "email": "info@marjanmarkelj.de",
                                    "telephone": "+4921037891625",
                                    "url": "https://marjanmarkelj.de/"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/programs": {
            "get": {
                "operationId": "listPrograms",
                "summary": "Aktuelle Programme mit Quellen",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Program"
                                    }
                                },
                                "example": [
                                    {
                                        "schemaVersion": "1.0",
                                        "updatedAt": "2026-09-13T17:43:43+00:00",
                                        "sources": [
                                            {
                                                "url": "https://marjanmarkelj.de/saxophon-lernen-erwachsene/",
                                                "title": "Saxophone Society Academy"
                                            }
                                        ],
                                        "id": "academy",
                                        "name": "Saxophone Society Academy",
                                        "audience": "Erwachsene Anfänger und Wiedereinsteiger",
                                        "summary": "16 wöchentliche Module innerhalb von 6 Monaten Begleitung.",
                                        "durationMonths": 6,
                                        "moduleCount": 16,
                                        "performanceChecks": 4,
                                        "features": [
                                            "Onboarding-Modul vor Beginn",
                                            "16 Module, jeweils ein Modul pro Woche",
                                            "Anschließend Freischaltung der Song Library",
                                            "4 individuelle Performance Checks",
                                            "Wöchentliche Online-Live-Sessions in der Gruppe",
                                            "Optionale individuelle 1:1-Sessions möglich; keine feste Inklusivzahl zugesagt",
                                            "Lebenslanger Community-Zugang einschließlich Community Challenges, Events und Webinaren; keine Zusage lebenslangen individuellen Coachings oder Zugriffs auf alle Kursinhalte"
                                        ],
                                        "url": "https://marjanmarkelj.de/saxophon-lernen-erwachsene/"
                                    },
                                    {
                                        "schemaVersion": "1.0",
                                        "updatedAt": "2026-09-13T17:43:43+00:00",
                                        "sources": [
                                            {
                                                "url": "https://marjanmarkelj.de/saxophon-coaching-fortgeschrittene/",
                                                "title": "Saxophone Society Circle"
                                            }
                                        ],
                                        "id": "circle",
                                        "name": "Saxophone Society Circle",
                                        "audience": "Fortgeschrittene Saxophonspieler",
                                        "summary": "Seasons von 3 Monaten mit mindestens 6 Monaten Buchungsdauer.",
                                        "seasonMonths": 3,
                                        "minimumBookingMonths": 6,
                                        "features": [
                                            "Pro Season ein Fokus: Sound, Rhythmus, Impro oder Performance",
                                            "Mindestbuchungsdauer: 6 Monate",
                                            "Gruppen-Masterclasses alle zwei Wochen; online und lokal möglich",
                                            "Modul-Inhalte alle zwei Wochen, zwischen den Masterclasses",
                                            "Individuelle 1:1-Sessions buchbar",
                                            "Lebenslanger Community-Zugang einschließlich Community Challenges, Events und Webinaren; keine Zusage lebenslangen individuellen Coachings oder Zugriffs auf alle Kursinhalte"
                                        ],
                                        "url": "https://marjanmarkelj.de/saxophon-coaching-fortgeschrittene/"
                                    }
                                ]
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/programs/{id}": {
            "get": {
                "operationId": "getProgram",
                "summary": "Ein Programm",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "academy",
                                "circle"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Program"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/compare": {
            "get": {
                "operationId": "comparePrograms",
                "summary": "Sachlicher Programmvergleich",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Comparison"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/search": {
            "get": {
                "operationId": "searchGuides",
                "summary": "Nur öffentliche freigegebene Inhalte",
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 300
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 10,
                            "default": 5
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Search"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/next-step": {
            "get": {
                "operationId": "getNextStep",
                "summary": "Passender Link, keine Anmeldung",
                "parameters": [
                    {
                        "name": "intent",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "consultation",
                                "freebie",
                                "webinar"
                            ],
                            "default": "consultation"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NextStep"
                                },
                                "example": {
                                    "schemaVersion": "1.0",
                                    "updatedAt": "2026-09-13T17:43:43+00:00",
                                    "sources": [
                                        {
                                            "url": "https://marjanmarkelj.de/#kontakt",
                                            "title": "Erstgespräch"
                                        }
                                    ],
                                    "intent": "consultation",
                                    "label": "Erstgespräch",
                                    "available": true,
                                    "url": "https://marjanmarkelj.de/#kontakt",
                                    "message": "Link öffnen; es wird nichts automatisch gebucht oder gesendet."
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/ask": {
            "get": {
                "operationId": "askQuestion",
                "summary": "Deterministische quellenbasierte Auskunft",
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 500
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Answer"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "operationId": "askQuestionPost",
                "summary": "Deterministische quellenbasierte Auskunft",
                "responses": {
                    "200": {
                        "description": "Aktuelle öffentliche Daten; sources enthalten überprüfbare Quellenlinks.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Answer"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Ungültige Eingabe, nicht verfügbar oder begrenzter Zugriff.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "query": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 500
                                    }
                                },
                                "required": [
                                    "query"
                                ],
                                "additionalProperties": false
                            },
                            "example": {
                                "query": "Wie lange dauert die Academy?"
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "description": "Einheitliche Fehlerantwort.",
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "description": "Maschinenlesbarer Fehlercode, z. B. invalid_program, rest_invalid_param, rate_limited."
                    },
                    "message": {
                        "type": "string",
                        "description": "Erklärung für Menschen."
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "integer",
                                "description": "HTTP-Status."
                            }
                        }
                    }
                }
            },
            "Source": {
                "type": "object",
                "required": [
                    "url",
                    "title"
                ],
                "properties": {
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "title": {
                        "type": "string"
                    }
                }
            },
            "Program": {
                "type": "object",
                "required": [
                    "id",
                    "name",
                    "summary",
                    "features",
                    "url",
                    "sources"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "id": {
                        "type": "string",
                        "enum": [
                            "academy",
                            "circle"
                        ]
                    },
                    "name": {
                        "type": "string"
                    },
                    "summary": {
                        "type": "string"
                    },
                    "features": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "durationMonths": {
                        "type": "integer"
                    },
                    "seasonMonths": {
                        "type": "integer"
                    },
                    "minimumBookingMonths": {
                        "type": "integer"
                    }
                }
            },
            "Document": {
                "type": "object",
                "required": [
                    "id",
                    "title",
                    "url",
                    "text"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "id": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "text": {
                        "type": "string"
                    },
                    "truncated": {
                        "type": "boolean"
                    },
                    "textCharacterLimit": {
                        "type": "integer"
                    }
                }
            },
            "NextStep": {
                "type": "object",
                "required": [
                    "intent",
                    "label",
                    "url",
                    "available",
                    "sources"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "intent": {
                        "type": "string",
                        "enum": [
                            "consultation",
                            "freebie",
                            "webinar"
                        ]
                    },
                    "label": {
                        "type": "string"
                    },
                    "url": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri"
                    },
                    "message": {
                        "type": "string"
                    },
                    "available": {
                        "type": "boolean",
                        "description": "Nur true erlaubt den Link als bestätigten nächsten Schritt zu empfehlen."
                    }
                }
            },
            "Company": {
                "type": "object",
                "required": [
                    "name",
                    "url",
                    "sources"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "name": {
                        "type": "string"
                    },
                    "brand": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "serviceArea": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "audiences": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "telephone": {
                        "type": "string"
                    },
                    "address": {
                        "type": "object",
                        "properties": {
                            "streetAddress": {
                                "type": "string"
                            },
                            "postalCode": {
                                "type": "string"
                            },
                            "addressLocality": {
                                "type": "string"
                            },
                            "addressCountry": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "Search": {
                "type": "object",
                "required": [
                    "query",
                    "results"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "query": {
                        "type": "string"
                    },
                    "results": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Document"
                        }
                    }
                }
            },
            "Answer": {
                "type": "object",
                "required": [
                    "query",
                    "answer",
                    "sources",
                    "nextStep"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "query": {
                        "type": "string"
                    },
                    "answer": {
                        "type": "string"
                    },
                    "nextStep": {
                        "$ref": "#/components/schemas/NextStep"
                    },
                    "matchedDocuments": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "answerType": {
                        "type": "string",
                        "enum": [
                            "source_excerpts",
                            "not_covered"
                        ]
                    }
                }
            },
            "Comparison": {
                "type": "object",
                "required": [
                    "programs",
                    "guidance",
                    "sources"
                ],
                "properties": {
                    "schemaVersion": {
                        "type": "string"
                    },
                    "updatedAt": {
                        "type": "string"
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Source"
                        }
                    },
                    "programs": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Program"
                        }
                    },
                    "guidance": {
                        "type": "string"
                    }
                }
            }
        }
    }
}