{ "openapi": "3.1.0", "info": { "title": "Geniefy API", "version": "1", "description": "Die API der KI-Betriebsebene für Hausverwaltungen: Anrufe, WhatsApp und E-Mail, Wissen, Agent, Weiterleitung, Integrationen, Kontakte, Aufgaben, Auswertungen, Abrechnung und verbundene Systeme. Die Verwaltung wird immer aus dem API-Schlüssel bestimmt.", "contact": { "name": "Geniefy", "email": "hello@geniefy.de", "url": "https://www.geniefy.de/developers" } }, "servers": [ { "url": "https://api.geniefy.de/v1" } ], "tags": [ { "name": "Anrufe", "description": "Jeder Anruf, den Ihr Agent annimmt oder führt, mit Zusammenfassung, Einordnung, Rolle der anrufenden Person und den daraus entstandenen Vorgängen. Die Liste entspricht der Anrufübersicht im Dashboard." }, { "name": "WhatsApp und E-Mail", "description": "Gespräche aus WhatsApp und dem verbundenen Postfach. Sie können mitlesen, Gespräche übernehmen, im Namen Ihres Teams antworten und E-Mails senden oder als Entwurf ablegen." }, { "name": "Wissen", "description": "Die Fragen und Antworten, auf die sich Ihr Agent in allen Kanälen stützt. Ein neuer Eintrag gilt sofort, es gibt keine Trainingszeit." }, { "name": "Abläufe", "description": "Abläufe sagen dem Agenten, wie er in einer bestimmten Situation vorgeht, etwa bei einem verlorenen Schlüssel oder einer Kündigung. Im Dashboard heißen sie Persona und Abläufe." }, { "name": "Agent", "description": "Name, Stimme, Begrüßung, Sprache und Verhalten Ihres Agenten sowie gesperrte Nummern. Das entspricht den Agent-Einstellungen im Dashboard." }, { "name": "Weiterleitung", "description": "Öffnungszeiten, Feiertage und die Regeln, nach denen Anrufe an Ihr Team, den Beirat oder den Notdienst durchgestellt werden." }, { "name": "Integrationen", "description": "Die Verbindung zu casavi, Facilioo oder DoNexus und welche Funktionen darüber laufen." }, { "name": "Kontakte und Objekte", "description": "Die Personen, Objekte und Einheiten, mit denen der Agent Anrufende erkennt und Anliegen zuordnet." }, { "name": "Aufgaben", "description": "Wenn eine Aktion eine menschliche Freigabe braucht, schlägt der Agent sie als Aufgabe vor. Sie prüfen den Vorschlag, korrigieren ihn bei Bedarf und geben ihn frei.", "x-beta": true }, { "name": "Auswertungen", "description": "Die Kennzahlen aus dem Bereich Auswertungen im Dashboard: Volumen, Themen, Objekte und Entwicklung über die Zeit." }, { "name": "Abrechnung", "description": "Verbrauch des laufenden Monats, Rechnungsdaten und Rechnungen als PDF." }, { "name": "Verbundene Systeme", "description": "Geniefy liegt als Betriebsebene über CRM, ERP und DMS Ihrer Verwaltung. Diese Endpunkte greifen über Geniefy auf die angebundenen Systeme zu: in einem einheitlichen Format, egal ob die Daten aus casavi, Facilioo oder DoNexus kommen.", "x-beta": true }, { "name": "Webhooks", "description": "Registrieren Sie Adressen, an die Geniefy Ereignisse sendet. Wie Sie Zustellungen prüfen, steht unter Webhooks empfangen.", "x-beta": true } ], "paths": { "/calls": { "get": { "operationId": "search_calls", "summary": "Anrufe auflisten", "description": "Gibt die Anrufe Ihrer Verwaltung zurück, neueste zuerst. Alle Filter lassen sich kombinieren. Wenn Sie Kategorie und Unterkategorie gleichzeitig angeben, müssen beide zur selben Einordnung gehören. Trifft ein Filter nur auf eine Nebenkategorie zu, enthält die Karte das Feld `matchedOn`.", "tags": [ "Anrufe" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "search_calls", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "category", "in": "query", "required": false, "description": "Eine oder mehrere Kategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.", "schema": { "description": "Eine oder mehrere Kategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.", "type": "string", "examples": [ "Repairs" ] } }, { "name": "subcategory", "in": "query", "required": false, "description": "Eine oder mehrere Unterkategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.", "schema": { "description": "Eine oder mehrere Unterkategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.", "type": "string", "examples": [ "Heating,HotWater" ] } }, { "name": "search", "in": "query", "required": false, "description": "Sucht ohne Beachtung der Groß- und Kleinschreibung in Name, Thema und Anruf-ID. Enthält die Suche nur Ziffern, wird auch die Telefonnummer durchsucht.", "schema": { "description": "Sucht ohne Beachtung der Groß- und Kleinschreibung in Name, Thema und Anruf-ID. Enthält die Suche nur Ziffern, wird auch die Telefonnummer durchsucht.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20, "examples": [ 20 ] } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Anrufkarten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "calls": { "type": "array", "items": { "type": "object", "properties": { "callId": { "type": "string" }, "timestamp": { "type": "integer" }, "timestampHuman": { "type": "string" }, "name": { "type": "string" }, "fromPhone": { "type": "string" }, "topic": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "duration": { "type": "number" } } } }, "total": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "example": { "calls": [ { "callId": "AJ_7tQm2KxV9pLr4", "timestamp": 1789374510148, "timestampHuman": "2026-09-14T08:28:30.148Z", "name": "Anna Schneider", "fromPhone": "+4915199990123", "topic": "Heizung im Bad bleibt seit gestern kalt", "category": "Repairs", "subcategory": "Heating", "duration": 142.6 } ], "total": 268, "nextCursor": "eyJvIjoyMH0" } } } }, "400": { "description": "INVALID_DATE_FORMAT: Ein Datum hat nicht das Format `YYYY-MM-DD`. INVALID_DATE_RANGE: `start_date` liegt nach `end_date`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{callId}": { "get": { "operationId": "get_call", "summary": "Anruf abrufen", "description": "Gibt einen Anruf mit Zusammenfassung, Rolle der anrufenden Person, Adresse, angelegten Vorgängen und Weiterleitung zurück. Eine unbekannte ID und die ID einer anderen Verwaltung ergeben beide `404 CALL_NOT_FOUND`. Das Abrufen markiert den Anruf nicht als gelesen.", "tags": [ "Anrufe" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "get_call", "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID aus einer Anrufkarte.", "schema": { "description": "ID aus einer Anrufkarte.", "type": "string", "examples": [ "AJ_7tQm2KxV9pLr4" ] } } ], "responses": { "200": { "description": "Das vollständige Anruf-Objekt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "timestamp": { "type": "integer" }, "timestampHuman": { "type": "string" }, "name": { "type": "string" }, "fromPhone": { "type": "string" }, "topic": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "duration": { "type": "number" }, "summary": { "type": "string" }, "callerRole": { "type": "string" }, "isAnonymous": { "type": "boolean" }, "address": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "buildingId": { "type": "string" }, "unitId": { "type": "string" }, "label": { "type": "string" } } } }, "secondaryCategories": { "type": "array", "items": {} }, "classificationConfidence": { "type": "number" }, "classificationNeedsReview": { "type": "boolean" }, "ticketCreated": { "type": "boolean" }, "tickets": { "type": "array", "items": { "type": "object", "properties": { "ticketId": { "type": "string" }, "displayNumber": { "type": "string" }, "system": { "type": "string" }, "appLink": { "type": "string" } } } }, "forwarding": {}, "callbackRequested": { "type": "boolean" }, "recordingUrl": { "type": "string" }, "transcriptUrl": { "type": "string" }, "taxonomyVersion": { "type": "string" } } }, "example": { "callId": "AJ_7tQm2KxV9pLr4", "timestamp": 1789374510148, "timestampHuman": "2026-09-14T08:28:30.148Z", "name": "Anna Schneider", "fromPhone": "+4915199990123", "topic": "Heizung im Bad bleibt seit gestern kalt", "category": "Repairs", "subcategory": "Heating", "duration": 142.6, "summary": "Frau Schneider meldet, dass der Heizkörper im Bad seit gestern Abend kalt bleibt. Die übrigen Räume sind warm. Ein Vorgang wurde angelegt und dem Heizungsbauer zugewiesen.", "callerRole": "tenant", "isAnonymous": false, "address": "Lindenstraße 12, 80331 München", "locations": [ { "buildingId": "bld_Linden12", "unitId": "unit_Linden12_WE04", "label": "WE 04" } ], "secondaryCategories": [], "classificationConfidence": 0.94, "classificationNeedsReview": false, "ticketCreated": true, "tickets": [ { "ticketId": "casavi:TK-20931", "displayNumber": "TK-20931", "system": "casavi", "appLink": "https://app.casavi.com/tickets/20931" } ], "forwarding": null, "callbackRequested": false, "recordingUrl": "https://files.geniefy.de/rec/AJ_7tQm2KxV9pLr4.mp3?sig=…", "transcriptUrl": "https://files.geniefy.de/tr/AJ_7tQm2KxV9pLr4.json?sig=…", "taxonomyVersion": "2026-07" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CALL_NOT_FOUND: Es gibt keinen Anruf mit dieser ID in Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{callId}/transcript": { "get": { "operationId": "get_call_transcript", "summary": "Transkript abrufen", "description": "Gibt das Gespräch als Folge von Redebeiträgen zurück. Jeder Beitrag nennt die Sprecherrolle und den Zeitpunkt in Millisekunden ab Gesprächsbeginn.", "tags": [ "Anrufe" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "get_call_transcript", "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "ID des Anrufs.", "schema": { "description": "ID des Anrufs.", "type": "string", "examples": [ "AJ_7tQm2KxV9pLr4" ] } } ], "responses": { "200": { "description": "Das Transkript des Anrufs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "callId": { "type": "string" }, "language": { "type": "string" }, "turns": { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "string" }, "offsetMs": { "type": "integer" }, "text": { "type": "string" } } } } } }, "example": { "callId": "AJ_7tQm2KxV9pLr4", "language": "de", "turns": [ { "speaker": "agent", "offsetMs": 0, "text": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster." }, { "speaker": "caller", "offsetMs": 6200, "text": "Hallo, bei mir im Bad wird die Heizung nicht mehr warm." }, { "speaker": "agent", "offsetMs": 9800, "text": "Das tut mir leid. Seit wann ist das so, und sind die anderen Räume warm?" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CALL_NOT_FOUND: Es gibt keinen Anruf mit dieser ID in Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/outbound": { "post": { "operationId": "start_outbound_call", "summary": "Ausgehenden Anruf starten", "description": "Der Agent ruft eine Person an, zum Beispiel für einen Rückruf oder um bei einem Dienstleister nachzufassen. Der Auftrag beschreibt, was der Agent erreichen soll. Ohne `scheduledAt` beginnt der Anruf innerhalb einer Minute. Das Ergebnis erscheint anschließend als normaler Anruf und über das Ereignis `call.completed`.", "tags": [ "Anrufe" ], "security": [ { "bearerAuth": [ "calls:write" ] } ], "x-scope": "calls:write", "x-mcp-tool": "start_outbound_call", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "description": "Telefonnummer im Format E.164.", "type": "string" }, "instruction": { "description": "Was der Agent im Gespräch klären soll, in ganzen Sätzen.", "type": "string" }, "contactId": { "description": "Verknüpft den Anruf mit einem Kontakt.", "type": "string" }, "relatedCallId": { "description": "Der Anruf, auf den sich dieser Rückruf bezieht.", "type": "string" }, "language": { "description": "Gesprächssprache, Standard ist die Hauptsprache des Agenten.", "type": "string", "enum": [ "de", "en" ] }, "scheduledAt": { "description": "Zeitpunkt in ISO 8601, frühestens jetzt und höchstens sieben Tage im Voraus.", "type": "string" } }, "required": [ "to", "instruction" ] }, "example": { "to": "+4915199990123", "instruction": "Frau Schneider mitteilen, dass der Heizungsbauer morgen zwischen 8 und 10 Uhr kommt, und fragen, ob jemand zu Hause ist.", "relatedCallId": "AJ_7tQm2KxV9pLr4", "language": "de" } } } }, "responses": { "202": { "description": "Der Anruf ist eingeplant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "outboundCallId": { "type": "string" }, "status": { "type": "string" }, "scheduledAt": { "type": "string" } } }, "example": { "outboundCallId": "ob_2Lq9Vt6", "status": "queued", "scheduledAt": "2026-09-14T09:02:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "operationId": "list_categories", "summary": "Kategorien auflisten", "description": "Gibt die Kategorien und Unterkategorien zurück, nach denen Ihre Anfragen eingeordnet werden. Rufen Sie diesen Endpunkt vor dem Filtern auf, denn die Werte sind exakt und hängen vom Kanal ab.", "tags": [ "Anrufe" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "list_categories", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Kanal, dessen Vokabular zurückgegeben wird.", "schema": { "description": "Kanal, dessen Vokabular zurückgegeben wird.", "type": "string", "enum": [ "voice", "whatsapp", "email" ], "default": "voice", "examples": [ "voice" ] } } ], "responses": { "200": { "description": "Das Klassifizierungsvokabular.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taxonomyVersion": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "subcategory": { "type": "string" } } } } } } } } }, "example": { "taxonomyVersion": "2026-07", "categories": [ { "category": "Emergency", "subcategories": [ { "subcategory": "EmergencyWater" }, { "subcategory": "EmergencyHeating" } ] }, { "category": "Repairs", "subcategories": [ { "subcategory": "Heating" }, { "subcategory": "Plumbing" }, { "subcategory": "WaterDamage" } ] }, { "category": "Accounting", "subcategories": [ { "subcategory": "OperatingCosts" }, { "subcategory": "AnnualStatement" } ] } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations": { "get": { "operationId": "list_conversations", "summary": "Gespräche auflisten", "description": "Gibt WhatsApp- und E-Mail-Verläufe zurück, zuletzt aktive zuerst.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "x-mcp-tool": "list_conversations", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Nur Gespräche dieses Kanals.", "schema": { "description": "Nur Gespräche dieses Kanals.", "type": "string", "enum": [ "whatsapp", "email" ], "examples": [ "whatsapp" ] } }, { "name": "status", "in": "query", "required": false, "description": "Nur offene oder nur abgeschlossene Gespräche.", "schema": { "description": "Nur offene oder nur abgeschlossene Gespräche.", "type": "string", "enum": [ "open", "closed" ] } }, { "name": "mode", "in": "query", "required": false, "description": "Nur Gespräche, die gerade der Agent oder eine Person führt.", "schema": { "description": "Nur Gespräche, die gerade der Agent oder eine Person führt.", "type": "string", "enum": [ "ai", "human" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "search", "in": "query", "required": false, "description": "Sucht in Name, Telefonnummer, E-Mail-Adresse und Betreff.", "schema": { "description": "Sucht in Name, Telefonnummer, E-Mail-Adresse und Betreff.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Gesprächen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "subject": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "unread": { "type": "boolean" }, "lastMessageAt": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": {} } }, "example": { "conversations": [ { "conversationId": "wa_9KfR2mXq71", "channel": "whatsapp", "status": "open", "mode": "ai", "contact": { "name": "Jonas Weber", "phone": "+4915199990456", "role": "tenant" }, "subject": "Wasserfleck an der Decke im Flur", "category": "Repairs", "subcategory": "WaterDamage", "unread": true, "lastMessageAt": "2026-09-14T17:42:10Z" } ], "total": 41, "nextCursor": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}": { "get": { "operationId": "get_conversation", "summary": "Gespräch abrufen", "description": "Gibt ein Gespräch mit allen Nachrichten und Anhängen zurück. Anhänge wie Fotos oder Sprachnachrichten kommen als signierte Links.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "x-mcp-tool": "get_conversation", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID des Gesprächs.", "schema": { "description": "ID des Gesprächs.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } } ], "responses": { "200": { "description": "Das Gespräch mit Nachrichten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "subject": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "unread": { "type": "boolean" }, "lastMessageAt": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "text": { "type": "string" }, "attachments": { "type": "array", "items": {} }, "sentAt": { "type": "string" }, "status": { "type": "string" } } } } } }, "example": { "conversationId": "wa_9KfR2mXq71", "channel": "whatsapp", "status": "open", "mode": "ai", "contact": { "name": "Jonas Weber", "phone": "+4915199990456", "role": "tenant" }, "subject": "Wasserfleck an der Decke im Flur", "category": "Repairs", "subcategory": "WaterDamage", "unread": true, "lastMessageAt": "2026-09-14T17:42:10Z", "messages": [ { "messageId": "msg_1", "direction": "inbound", "author": "contact", "text": "Hallo, im Flur ist ein Wasserfleck an der Decke. Foto anbei.", "attachments": [ { "type": "image", "url": "https://files.geniefy.de/wa/msg_1.jpg?sig=…" } ], "sentAt": "2026-09-14T17:40:55Z" }, { "messageId": "msg_2", "direction": "outbound", "author": "agent", "text": "Danke für das Foto. Ist der Fleck feucht, und tropft es gerade?", "attachments": [], "sentAt": "2026-09-14T17:41:03Z", "status": "read" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/live": { "get": { "operationId": "live-gespraeche", "summary": "Laufende Gespräche abrufen", "description": "Gibt die WhatsApp-Gespräche zurück, in denen in den letzten 15 Minuten geschrieben wurde. Das entspricht der Ansicht WhatsApp live im Dashboard und eignet sich für eigene Leitstände.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "responses": { "200": { "description": "Die aktiven Gespräche.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "subject": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "unread": { "type": "boolean" }, "lastMessageAt": { "type": "string" }, "typing": { "type": "string" } } } } } }, "example": { "conversations": [ { "conversationId": "wa_9KfR2mXq71", "channel": "whatsapp", "status": "open", "mode": "ai", "contact": { "name": "Jonas Weber", "phone": "+4915199990456", "role": "tenant" }, "subject": "Wasserfleck an der Decke im Flur", "category": "Repairs", "subcategory": "WaterDamage", "unread": true, "lastMessageAt": "2026-09-14T17:42:10Z", "typing": "contact" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}/messages": { "post": { "operationId": "send_message", "summary": "Nachricht senden", "description": "Sendet eine Nachricht im Namen Ihres Teams. Bei WhatsApp muss das Gespräch vorher übernommen sein (`mode` ist `human`), damit Agent und Mensch nicht gleichzeitig antworten. Außerhalb des 24-Stunden-Fensters von WhatsApp ist nur eine freigegebene Vorlage möglich.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "send_message", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID des Gesprächs.", "schema": { "description": "ID des Gesprächs.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "Inhalt der Nachricht, höchstens 4.096 Zeichen.", "type": "string" }, "attachments": { "description": "Bis zu fünf Anhänge mit `type` und öffentlich erreichbarer `url`.", "type": "array", "items": { "type": "object" } } }, "required": [ "text" ] }, "example": { "text": "Guten Abend Herr Weber, unser Hausmeister schaut sich den Fleck morgen früh an. Bitte stellen Sie einen Eimer unter, falls es tropft." } } } }, "responses": { "201": { "description": "Die gesendete Nachricht.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messageId": { "type": "string" }, "direction": { "type": "string" }, "author": { "type": "string" }, "text": { "type": "string" }, "sentAt": { "type": "string" }, "status": { "type": "string" } } }, "example": { "messageId": "msg_3", "direction": "outbound", "author": "human", "text": "Guten Abend Herr Weber, unser Hausmeister schaut sich den Fleck morgen früh an. Bitte stellen Sie einen Eimer unter, falls es tropft.", "sentAt": "2026-09-14T17:45:12Z", "status": "sent" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CONVERSATION_NOT_TAKEN_OVER: Das Gespräch muss vor dem Senden übernommen werden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}/mode": { "put": { "operationId": "set_conversation_mode", "summary": "Gespräch übernehmen oder zurückgeben", "description": "Mit `human` übernimmt Ihr Team das Gespräch und der Agent schweigt. Mit `ai` geben Sie es an den Agenten zurück, der den bisherigen Verlauf kennt und dort weitermacht.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "set_conversation_mode", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "ID des Gesprächs.", "schema": { "description": "ID des Gesprächs.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "Wer das Gespräch führt.", "type": "string", "enum": [ "ai", "human" ] } }, "required": [ "mode" ] }, "example": { "mode": "human" } } } }, "responses": { "200": { "description": "Das aktualisierte Gespräch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "conversationId": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "mode": { "type": "string" }, "contact": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "role": { "type": "string" } } }, "subject": { "type": "string" }, "category": { "type": "string" }, "subcategory": { "type": "string" }, "unread": { "type": "boolean" }, "lastMessageAt": { "type": "string" }, "takenOverBy": { "type": "string" } } }, "example": { "conversationId": "wa_9KfR2mXq71", "channel": "whatsapp", "status": "open", "mode": "human", "contact": { "name": "Jonas Weber", "phone": "+4915199990456", "role": "tenant" }, "subject": "Wasserfleck an der Decke im Flur", "category": "Repairs", "subcategory": "WaterDamage", "unread": true, "lastMessageAt": "2026-09-14T17:42:10Z", "takenOverBy": "maria.hoffmann@hv-muster.de" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails": { "post": { "operationId": "send_email", "summary": "E-Mail senden", "description": "Sendet eine E-Mail über das verbundene Postfach oder legt sie als Entwurf zur Prüfung an. Mit `conversationId` wird die E-Mail als Antwort im bestehenden Verlauf abgelegt.", "tags": [ "WhatsApp und E-Mail" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "send_email", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "description": "Empfängeradressen.", "type": "array", "items": { "type": "string" } }, "cc": { "description": "Adressen in Kopie.", "type": "array", "items": { "type": "string" } }, "subject": { "description": "Betreff der E-Mail.", "type": "string" }, "text": { "description": "Inhalt als Text. Absätze trennen Sie mit einer Leerzeile.", "type": "string" }, "conversationId": { "description": "Verlauf, in dem die E-Mail als Antwort erscheint.", "type": "string" }, "sendMode": { "description": "Sofort senden oder als Entwurf ablegen.", "type": "string", "enum": [ "send", "draft" ], "default": "send" } }, "required": [ "to", "subject", "text" ] }, "example": { "to": [ "heizung@huber-heizungsbau.de" ], "subject": "Auftrag TK-20931: Heizkörper Bad, Lindenstraße 12, WE 04", "text": "Guten Tag Herr Huber,\n\nbitte prüfen Sie den Heizkörper im Bad der WE 04. Die Mieterin ist morgen ab 8 Uhr zu Hause.\n\nViele Grüße\nHausverwaltung Muster", "sendMode": "draft" } } } }, "responses": { "201": { "description": "Die E-Mail oder der Entwurf.", "content": { "application/json": { "schema": { "type": "object", "properties": { "emailId": { "type": "string" }, "status": { "type": "string" }, "conversationId": { "type": "string" }, "createdAt": { "type": "string" } } }, "example": { "emailId": "em_6Tq1Wd3", "status": "draft", "conversationId": "em_thread_44Kp", "createdAt": "2026-09-14T09:05:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs": { "get": { "operationId": "faqs-auflisten", "summary": "FAQs auflisten", "description": "Gibt alle Fragen und Antworten zurück, die Ihr Agent kennt.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit FAQs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "faqs": { "type": "array", "items": { "type": "object", "properties": { "faqId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "example": { "faqs": [ { "faqId": "faq_3Hc8wQ2p", "question": "Wann wird die Betriebskostenabrechnung verschickt?", "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.", "createdAt": "2026-06-02T09:14:00Z", "updatedAt": "2026-09-01T11:20:00Z" } ], "total": 87, "nextCursor": "eyJvIjoyMH0" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_faq", "summary": "FAQ anlegen", "description": "Legt einen Eintrag an, den der Agent ab sofort in allen Kanälen nutzt. Ähnelt die Frage stark einem vorhandenen Eintrag, wird er trotzdem angelegt, und die Antwort enthält `duplicateWarning` mit dem ähnlichen Eintrag.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "x-mcp-tool": "create_faq", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "description": "Die Frage, so wie Anrufende sie stellen würden.", "type": "string" }, "answer": { "description": "Die Antwort in ganzen Sätzen.", "type": "string" } }, "required": [ "question", "answer" ] }, "example": { "question": "Wo finde ich das Protokoll der letzten Eigentümerversammlung?", "answer": "Das Protokoll steht im Eigentümerportal unter Dokumente. Auf Wunsch schicken wir es Ihnen per E-Mail." } } } }, "responses": { "201": { "description": "Der neue Eintrag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "faq": { "type": "object", "properties": { "faqId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "duplicateWarning": {} } }, "example": { "faq": { "faqId": "faq_9Lm4Tz7", "question": "Wo finde ich das Protokoll der letzten Eigentümerversammlung?", "answer": "Das Protokoll steht im Eigentümerportal unter Dokumente. Auf Wunsch schicken wir es Ihnen per E-Mail.", "createdAt": "2026-09-14T10:00:00Z", "updatedAt": "2026-09-14T10:00:00Z" }, "duplicateWarning": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs/search": { "get": { "operationId": "search_knowledge", "summary": "FAQs durchsuchen", "description": "Findet Einträge nach Bedeutung und nicht nur nach Wortlaut. So findet die Suche nach Nebenkosten auch eine Antwort, in der Betriebskosten steht.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "x-mcp-tool": "search_knowledge", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Frage oder Stichwort.", "schema": { "description": "Frage oder Stichwort.", "type": "string", "examples": [ "Nebenkostenabrechnung" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Treffer, beste Übereinstimmung zuerst.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "faqId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "score": { "type": "number" } } } } } }, "example": { "results": [ { "faqId": "faq_3Hc8wQ2p", "question": "Wann wird die Betriebskostenabrechnung verschickt?", "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.", "createdAt": "2026-06-02T09:14:00Z", "updatedAt": "2026-09-01T11:20:00Z", "score": 0.91 } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs/{faqId}": { "get": { "operationId": "faq-abrufen", "summary": "FAQ abrufen", "description": "Gibt einen einzelnen Eintrag zurück.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "ID des Eintrags.", "schema": { "description": "ID des Eintrags.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "responses": { "200": { "description": "Der Eintrag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "faqId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "faqId": "faq_3Hc8wQ2p", "question": "Wann wird die Betriebskostenabrechnung verschickt?", "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.", "createdAt": "2026-06-02T09:14:00Z", "updatedAt": "2026-09-01T11:20:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update_faq", "summary": "FAQ ändern", "description": "Ersetzt Frage und Antwort eines Eintrags.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "x-mcp-tool": "update_faq", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "ID des Eintrags.", "schema": { "description": "ID des Eintrags.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "description": "Die neue Frage.", "type": "string" }, "answer": { "description": "Die neue Antwort.", "type": "string" } }, "required": [ "question", "answer" ] }, "example": { "question": "Wann wird die Betriebskostenabrechnung verschickt?", "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal." } } } }, "responses": { "200": { "description": "Der geänderte Eintrag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "faq": { "type": "object", "properties": { "faqId": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "duplicateWarning": {} } }, "example": { "faq": { "faqId": "faq_3Hc8wQ2p", "question": "Wann wird die Betriebskostenabrechnung verschickt?", "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.", "createdAt": "2026-06-02T09:14:00Z", "updatedAt": "2026-09-01T11:20:00Z" }, "duplicateWarning": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "faq-loeschen", "summary": "FAQ löschen", "description": "Löscht einen Eintrag. Der Agent nutzt ihn ab sofort nicht mehr.", "tags": [ "Wissen" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "ID des Eintrags.", "schema": { "description": "ID des Eintrags.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/procedures": { "get": { "operationId": "list_procedures", "summary": "Abläufe auflisten", "description": "Gibt alle Abläufe zurück, die der Agent in bestimmten Situationen befolgt.", "tags": [ "Abläufe" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "x-mcp-tool": "list_procedures", "responses": { "200": { "description": "Alle Abläufe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedures": { "type": "array", "items": { "type": "object", "properties": { "procedureId": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "updatedAt": { "type": "string" } } } } } }, "example": { "procedures": [ { "procedureId": "prc_W4n7Lx1", "name": "Schlüsselverlust", "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.", "steps": [ "Objekt, Einheit und Art des Schlüssels erfragen.", "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.", "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen." ], "channels": [ "voice", "whatsapp", "email" ], "enabled": true, "updatedAt": "2026-08-21T15:03:00Z" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "ablauf-anlegen", "summary": "Ablauf anlegen", "description": "Legt einen Ablauf an. `trigger` beschreibt in einem Satz, wann er gilt, `steps` sagt dem Agenten Schritt für Schritt, was zu tun ist.", "tags": [ "Abläufe" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Kurzer Name, der im Dashboard erscheint.", "type": "string" }, "trigger": { "description": "Situation, in der der Ablauf gilt.", "type": "string" }, "steps": { "description": "Die Schritte in der richtigen Reihenfolge.", "type": "array", "items": { "type": "string" } }, "channels": { "description": "Kanäle, in denen der Ablauf gilt. Standard sind alle.", "type": "array", "items": { "type": "string", "enum": [ "voice", "whatsapp", "email" ] } }, "enabled": { "description": "Ob der Ablauf aktiv ist.", "type": "boolean", "default": true } }, "required": [ "name", "trigger", "steps" ] }, "example": { "name": "Schlüsselverlust", "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.", "steps": [ "Objekt, Einheit und Art des Schlüssels erfragen.", "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.", "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen." ], "channels": [ "voice", "whatsapp", "email" ] } } } }, "responses": { "201": { "description": "Der neue Ablauf.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedureId": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "updatedAt": { "type": "string" } } }, "example": { "procedureId": "prc_W4n7Lx1", "name": "Schlüsselverlust", "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.", "steps": [ "Objekt, Einheit und Art des Schlüssels erfragen.", "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.", "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen." ], "channels": [ "voice", "whatsapp", "email" ], "enabled": true, "updatedAt": "2026-08-21T15:03:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/procedures/{procedureId}": { "put": { "operationId": "ablauf-aendern", "summary": "Ablauf ändern", "description": "Ersetzt einen Ablauf vollständig.", "tags": [ "Abläufe" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "procedureId", "in": "path", "required": true, "description": "ID des Ablaufs.", "schema": { "description": "ID des Ablaufs.", "type": "string", "examples": [ "prc_W4n7Lx1" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trigger": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } } }, "example": { "name": "Schlüsselverlust", "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.", "steps": [ "Objekt, Einheit und Art des Schlüssels erfragen.", "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.", "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen." ], "channels": [ "voice", "whatsapp" ], "enabled": true } } } }, "responses": { "200": { "description": "Der geänderte Ablauf.", "content": { "application/json": { "schema": { "type": "object", "properties": { "procedureId": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "channels": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "updatedAt": { "type": "string" } } }, "example": { "procedureId": "prc_W4n7Lx1", "name": "Schlüsselverlust", "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.", "steps": [ "Objekt, Einheit und Art des Schlüssels erfragen.", "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.", "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen." ], "channels": [ "voice", "whatsapp" ], "enabled": true, "updatedAt": "2026-08-21T15:03:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "ablauf-loeschen", "summary": "Ablauf löschen", "description": "Löscht einen Ablauf.", "tags": [ "Abläufe" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "procedureId", "in": "path", "required": true, "description": "ID des Ablaufs.", "schema": { "description": "ID des Ablaufs.", "type": "string", "examples": [ "prc_W4n7Lx1" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/settings": { "get": { "operationId": "get_agent_settings", "summary": "Agent-Einstellungen abrufen", "description": "Gibt Name, Stimme, Begrüßung und Verhalten Ihres Agenten zurück.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "x-mcp-tool": "get_agent_settings", "responses": { "200": { "description": "Die aktuellen Einstellungen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentName": { "type": "string" }, "voiceId": { "type": "string" }, "primaryLanguage": { "type": "string" }, "greeting": { "type": "object", "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "callRecordingConsent": { "type": "boolean" }, "notificationEmail": { "type": "string" }, "fallbackPhone": { "type": "string" }, "voiceSpeed": { "type": "integer" }, "voiceEmotion": { "type": "string" }, "ambientNoise": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "volume": { "type": "number" } } }, "transcriptionWords": { "type": "array", "items": { "type": "string" } }, "pronunciations": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "spokenAs": { "type": "string" } } } }, "updatedAt": { "type": "string" } } }, "example": { "agentName": "Lena", "voiceId": "de-female-warm-2", "primaryLanguage": "de", "greeting": { "de": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster.", "en": "Hello, you are speaking with Lena, the digital assistant of Hausverwaltung Muster." }, "callRecordingConsent": true, "notificationEmail": "service@hv-muster.de", "fallbackPhone": "+498912345670", "voiceSpeed": 1, "voiceEmotion": "calm", "ambientNoise": { "enabled": false, "volume": 0.2 }, "transcriptionWords": [ "WEG", "Hausgeld", "Sondereigentum" ], "pronunciations": [ { "word": "WEG", "spokenAs": "W E G" } ], "updatedAt": "2026-09-10T08:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_agent_settings", "summary": "Agent-Einstellungen ändern", "description": "Ändert nur die Felder, die Sie mitsenden. Änderungen gelten ab dem nächsten Anruf oder der nächsten Nachricht.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:write" ] } ], "x-scope": "agent:write", "x-mcp-tool": "update_agent_settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentName": { "description": "Name, mit dem sich der Agent vorstellt.", "type": "string" }, "voiceId": { "description": "Stimme aus `GET /agent/voices`.", "type": "string" }, "greeting": { "description": "Begrüßung je Sprache mit den Schlüsseln `de` und `en`.", "type": "object" }, "primaryLanguage": { "description": "Sprache, in der Gespräche beginnen.", "type": "string", "enum": [ "de", "en" ] }, "callRecordingConsent": { "description": "Ob der Agent zu Beginn die Einwilligung zur Aufnahme einholt.", "type": "boolean" }, "notificationEmail": { "description": "Adresse für Zusammenfassungen und Hinweise.", "type": "string" }, "fallbackPhone": { "description": "Nummer, an die bei einer Störung durchgestellt wird.", "type": "string" }, "voiceSpeed": { "description": "Sprechtempo zwischen 0,8 und 1,2.", "type": "number" }, "pronunciations": { "description": "Wörter mit Aussprache, jeweils `word` und `spokenAs`.", "type": "array", "items": { "type": "object" } } } }, "example": { "voiceSpeed": 0.95, "greeting": { "de": "Guten Tag, Sie sprechen mit Lena von der Hausverwaltung Muster. Wie kann ich helfen?" } } } } }, "responses": { "200": { "description": "Die vollständigen, aktualisierten Einstellungen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentName": { "type": "string" }, "voiceId": { "type": "string" }, "primaryLanguage": { "type": "string" }, "greeting": { "type": "object", "properties": { "de": { "type": "string" }, "en": { "type": "string" } } }, "callRecordingConsent": { "type": "boolean" }, "notificationEmail": { "type": "string" }, "fallbackPhone": { "type": "string" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": "string" }, "ambientNoise": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "volume": { "type": "number" } } }, "transcriptionWords": { "type": "array", "items": { "type": "string" } }, "pronunciations": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "spokenAs": { "type": "string" } } } }, "updatedAt": { "type": "string" } } }, "example": { "agentName": "Lena", "voiceId": "de-female-warm-2", "primaryLanguage": "de", "greeting": { "de": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster.", "en": "Hello, you are speaking with Lena, the digital assistant of Hausverwaltung Muster." }, "callRecordingConsent": true, "notificationEmail": "service@hv-muster.de", "fallbackPhone": "+498912345670", "voiceSpeed": 0.95, "voiceEmotion": "calm", "ambientNoise": { "enabled": false, "volume": 0.2 }, "transcriptionWords": [ "WEG", "Hausgeld", "Sondereigentum" ], "pronunciations": [ { "word": "WEG", "spokenAs": "W E G" } ], "updatedAt": "2026-09-10T08:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/voices": { "get": { "operationId": "stimmen-auflisten", "summary": "Stimmen auflisten", "description": "Gibt die verfügbaren Stimmen mit einer kurzen Hörprobe zurück.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "parameters": [ { "name": "language", "in": "query", "required": false, "description": "Nur Stimmen dieser Sprache.", "schema": { "description": "Nur Stimmen dieser Sprache.", "type": "string", "enum": [ "de", "en" ], "examples": [ "de" ] } } ], "responses": { "200": { "description": "Die Stimmen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "voiceId": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "style": { "type": "string" }, "sampleUrl": { "type": "string" } } } } } }, "example": { "voices": [ { "voiceId": "de-female-warm-2", "name": "Lena", "language": "de", "style": "warm", "sampleUrl": "https://files.geniefy.de/voices/de-female-warm-2.mp3" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/voices/preview": { "post": { "operationId": "stimme-probehoeren", "summary": "Stimme probehören", "description": "Erzeugt eine Hörprobe mit Ihrem eigenen Text, etwa um eine neue Begrüßung zu prüfen.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "Text, höchstens 500 Zeichen.", "type": "string" }, "voiceId": { "description": "Die Stimme.", "type": "string" }, "voiceSpeed": { "description": "Sprechtempo zwischen 0,8 und 1,2.", "type": "number" } }, "required": [ "text", "voiceId" ] }, "example": { "text": "Guten Tag, Sie sprechen mit Lena von der Hausverwaltung Muster.", "voiceId": "de-female-warm-2" } } } }, "responses": { "200": { "description": "Ein Link auf die Audiodatei.", "content": { "application/json": { "schema": { "type": "object", "properties": { "audioUrl": { "type": "string" }, "expiresAt": { "type": "string" } } }, "example": { "audioUrl": "https://files.geniefy.de/tts/pv_81Kd.mp3?sig=…", "expiresAt": "2026-09-14T10:15:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/blocked-numbers": { "get": { "operationId": "gesperrte-nummern", "summary": "Gesperrte Nummern auflisten", "description": "Gibt die Nummern zurück, deren Anrufe und Nachrichten der Agent nicht annimmt.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "responses": { "200": { "description": "Die gesperrten Nummern.", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockedNumbers": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "reason": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "example": { "blockedNumbers": [ { "phone": "+4930555000111", "reason": "Werbeanrufe", "createdAt": "2026-07-03T13:00:00Z" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "block_number", "summary": "Nummer sperren", "description": "Sperrt eine Nummer für Anrufe und WhatsApp.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:write" ] } ], "x-scope": "agent:write", "x-mcp-tool": "block_number", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "description": "Nummer im Format E.164.", "type": "string" }, "reason": { "description": "Interner Grund, sichtbar im Dashboard.", "type": "string" } }, "required": [ "phone" ] }, "example": { "phone": "+4930555000111", "reason": "Werbeanrufe" } } } }, "responses": { "201": { "description": "Der Eintrag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string" }, "reason": { "type": "string" }, "createdAt": { "type": "string" } } }, "example": { "phone": "+4930555000111", "reason": "Werbeanrufe", "createdAt": "2026-09-14T10:20:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/blocked-numbers/{phone}": { "delete": { "operationId": "nummer-entsperren", "summary": "Nummer entsperren", "description": "Hebt die Sperre einer Nummer auf.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:write" ] } ], "x-scope": "agent:write", "parameters": [ { "name": "phone", "in": "path", "required": true, "description": "Nummer im Format E.164.", "schema": { "description": "Nummer im Format E.164.", "type": "string", "examples": [ "+4930555000111" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding": { "get": { "operationId": "get_forwarding", "summary": "Weiterleitung abrufen", "description": "Gibt Öffnungszeiten, Feiertagsregelung und alle Weiterleitungsregeln zurück.", "tags": [ "Weiterleitung" ], "security": [ { "bearerAuth": [ "forwarding:read" ] } ], "x-scope": "forwarding:read", "x-mcp-tool": "get_forwarding", "responses": { "200": { "description": "Die Konfiguration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" }, "openingHours": { "type": "object", "properties": { "timezone": { "type": "string" }, "monday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "tuesday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "wednesday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "thursday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "friday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "saturday": { "type": "object", "properties": { "open": { "type": "boolean" } } }, "sunday": { "type": "object", "properties": { "open": { "type": "boolean" } } } } }, "holidays": { "type": "object", "properties": { "region": { "type": "string" }, "closedOnHolidays": { "type": "boolean" }, "openOn": { "type": "array", "items": {} } } }, "rules": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "kind": { "type": "string" }, "enabled": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "target": { "type": "string" }, "window": { "type": "string" }, "callers": { "type": "array", "items": { "type": "string" } } } } }, "updatedAt": { "type": "string" } } }, "example": { "version": 7, "openingHours": { "timezone": "Europe/Berlin", "monday": { "open": true, "from": "08:00", "to": "17:00" }, "tuesday": { "open": true, "from": "08:00", "to": "17:00" }, "wednesday": { "open": true, "from": "08:00", "to": "17:00" }, "thursday": { "open": true, "from": "08:00", "to": "17:00" }, "friday": { "open": true, "from": "08:00", "to": "13:00" }, "saturday": { "open": false }, "sunday": { "open": false } }, "holidays": { "region": "BY", "closedOnHolidays": true, "openOn": [] }, "rules": [ { "ruleId": "rl_Emergency1", "kind": "role", "enabled": true, "roles": [ "tenant", "owner" ], "trigger": "emergency", "target": "+498912345699", "window": "always" }, { "ruleId": "rl_Board2", "kind": "role", "enabled": true, "roles": [ "advisoryBoard" ], "trigger": "any", "target": "+498912345677", "window": "openingHours" }, { "ruleId": "rl_Vip3", "kind": "vip", "enabled": true, "callers": [ "+4915199990789" ], "target": "+498912345671", "window": "openingHours" } ], "updatedAt": "2026-09-02T07:45:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "weiterleitung-ersetzen", "summary": "Weiterleitung ersetzen", "description": "Ersetzt die gesamte Konfiguration. Senden Sie die `version`, die Sie zuletzt gelesen haben. Hat sich die Konfiguration inzwischen geändert, antwortet die API mit `409 VERSION_CONFLICT`, und nichts wird überschrieben.", "tags": [ "Weiterleitung" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "description": "Zuletzt gelesene Version.", "type": "integer" }, "openingHours": { "description": "Öffnungszeiten je Wochentag mit `open`, `from` und `to`.", "type": "object" }, "holidays": { "description": "Bundesland als `region` und ob an Feiertagen geschlossen ist.", "type": "object" }, "rules": { "description": "Höchstens 40 Regeln. Regeln werden von oben nach unten geprüft.", "type": "array", "items": { "type": "object" } } }, "required": [ "version", "openingHours", "holidays", "rules" ] }, "example": { "version": 7, "openingHours": { "timezone": "Europe/Berlin", "monday": { "open": true, "from": "08:00", "to": "17:00" }, "tuesday": { "open": true, "from": "08:00", "to": "17:00" }, "wednesday": { "open": true, "from": "08:00", "to": "17:00" }, "thursday": { "open": true, "from": "08:00", "to": "17:00" }, "friday": { "open": true, "from": "08:00", "to": "13:00" }, "saturday": { "open": false }, "sunday": { "open": false } }, "holidays": { "region": "BY", "closedOnHolidays": true, "openOn": [] }, "rules": [ { "ruleId": "rl_Emergency1", "kind": "role", "enabled": true, "roles": [ "tenant", "owner" ], "trigger": "emergency", "target": "+498912345699", "window": "always" } ] } } } }, "responses": { "200": { "description": "Die gespeicherte Konfiguration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer" }, "openingHours": { "type": "object", "properties": { "timezone": { "type": "string" }, "monday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "tuesday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "wednesday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "thursday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "friday": { "type": "object", "properties": { "open": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" } } }, "saturday": { "type": "object", "properties": { "open": { "type": "boolean" } } }, "sunday": { "type": "object", "properties": { "open": { "type": "boolean" } } } } }, "holidays": { "type": "object", "properties": { "region": { "type": "string" }, "closedOnHolidays": { "type": "boolean" }, "openOn": { "type": "array", "items": {} } } }, "rules": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "kind": { "type": "string" }, "enabled": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "target": { "type": "string" }, "window": { "type": "string" } } } }, "updatedAt": { "type": "string" } } }, "example": { "version": 8, "openingHours": { "timezone": "Europe/Berlin", "monday": { "open": true, "from": "08:00", "to": "17:00" }, "tuesday": { "open": true, "from": "08:00", "to": "17:00" }, "wednesday": { "open": true, "from": "08:00", "to": "17:00" }, "thursday": { "open": true, "from": "08:00", "to": "17:00" }, "friday": { "open": true, "from": "08:00", "to": "13:00" }, "saturday": { "open": false }, "sunday": { "open": false } }, "holidays": { "region": "BY", "closedOnHolidays": true, "openOn": [] }, "rules": [ { "ruleId": "rl_Emergency1", "kind": "role", "enabled": true, "roles": [ "tenant", "owner" ], "trigger": "emergency", "target": "+498912345699", "window": "always" } ], "updatedAt": "2026-09-02T07:45:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "VERSION_CONFLICT: Die Konfiguration wurde seit Ihrem letzten Lesen geändert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding/rules": { "post": { "operationId": "regel-anlegen", "summary": "Weiterleitungsregel anlegen", "description": "Fügt eine Regel am Ende der Liste hinzu. `kind` bestimmt die Art: `role` leitet nach Rolle und Anliegen weiter, `vip` leitet bestimmte Nummern immer durch, `pin` stellt nach Eingabe einer PIN durch.", "tags": [ "Weiterleitung" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Art der Regel.", "type": "string", "enum": [ "role", "vip", "pin" ] }, "target": { "description": "Zielnummer im Format E.164.", "type": "string" }, "window": { "description": "Wann die Regel gilt.", "type": "string", "enum": [ "always", "openingHours", "outsideOpeningHours" ], "default": "always" }, "roles": { "description": "Bei `role`: Rollen, für die die Regel gilt.", "type": "array", "items": { "type": "string" } }, "trigger": { "description": "Bei `role`: `any` oder `emergency`.", "type": "string" }, "callers": { "description": "Bei `vip`: bis zu 50 Nummern.", "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "target" ] }, "example": { "kind": "role", "roles": [ "serviceProvider" ], "trigger": "any", "target": "+498912345672", "window": "openingHours" } } } }, "responses": { "201": { "description": "Die neue Regel.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ruleId": { "type": "string" }, "kind": { "type": "string" }, "enabled": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "trigger": { "type": "string" }, "target": { "type": "string" }, "window": { "type": "string" } } }, "example": { "ruleId": "rl_Svc4", "kind": "role", "enabled": true, "roles": [ "serviceProvider" ], "trigger": "any", "target": "+498912345672", "window": "openingHours" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding/rules/{ruleId}": { "delete": { "operationId": "regel-loeschen", "summary": "Weiterleitungsregel löschen", "description": "Entfernt eine Regel.", "tags": [ "Weiterleitung" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "ID der Regel.", "schema": { "description": "ID der Regel.", "type": "string", "examples": [ "rl_Svc4" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations": { "get": { "operationId": "integration-abrufen", "summary": "Anbindung abrufen", "description": "Gibt zurück, mit welchem System Geniefy verbunden ist und welche Funktionen aktiv sind.", "tags": [ "Integrationen" ], "security": [ { "bearerAuth": [ "integrations:read" ] } ], "x-scope": "integrations:read", "responses": { "200": { "description": "Die Anbindung.", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationType": { "type": "string" }, "status": { "type": "string" }, "features": { "type": "object", "properties": { "createTickets": { "type": "boolean" }, "assignTickets": { "type": "boolean" }, "lookupDocuments": { "type": "boolean" }, "identifyCallers": { "type": "boolean" }, "readOwnersMeetings": { "type": "boolean" } } }, "connectedAt": { "type": "string" }, "lastSyncAt": { "type": "string" } } }, "example": { "integrationType": "casavi", "status": "connected", "features": { "createTickets": true, "assignTickets": true, "lookupDocuments": true, "identifyCallers": true, "readOwnersMeetings": true }, "connectedAt": "2026-05-12T09:00:00Z", "lastSyncAt": "2026-09-14T08:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "integration-aendern", "summary": "Anbindung konfigurieren", "description": "Legt das System und die aktiven Funktionen fest. Zugangsdaten werden verschlüsselt gespeichert und nie wieder ausgegeben. Mit `geniefy` verwaltet Geniefy Kontakte und Vorgänge selbst.", "tags": [ "Integrationen" ], "security": [ { "bearerAuth": [ "integrations:write" ] } ], "x-scope": "integrations:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationType": { "description": "Das angebundene System.", "type": "string", "enum": [ "geniefy", "casavi", "facilioo", "donexus" ] }, "features": { "description": "Funktionen, die ein- oder ausgeschaltet werden.", "type": "object" }, "credentials": { "description": "Zugangsdaten des Systems, zum Beispiel ein API-Token.", "type": "object" } }, "required": [ "integrationType" ] }, "example": { "integrationType": "casavi", "features": { "createTickets": true, "lookupDocuments": true }, "credentials": { "apiToken": "cas_…" } } } } }, "responses": { "200": { "description": "Die gespeicherte Anbindung.", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationType": { "type": "string" }, "status": { "type": "string" }, "features": { "type": "object", "properties": { "createTickets": { "type": "boolean" }, "assignTickets": { "type": "boolean" }, "lookupDocuments": { "type": "boolean" }, "identifyCallers": { "type": "boolean" }, "readOwnersMeetings": { "type": "boolean" } } }, "connectedAt": { "type": "string" }, "lastSyncAt": { "type": "string" } } }, "example": { "integrationType": "casavi", "status": "pending", "features": { "createTickets": true, "assignTickets": true, "lookupDocuments": true, "identifyCallers": true, "readOwnersMeetings": true }, "connectedAt": "2026-05-12T09:00:00Z", "lastSyncAt": "2026-09-14T08:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/test": { "post": { "operationId": "integration-testen", "summary": "Anbindung testen", "description": "Prüft Verbindung und Berechtigungen, ohne Daten zu verändern.", "tags": [ "Integrationen" ], "security": [ { "bearerAuth": [ "integrations:write" ] } ], "x-scope": "integrations:write", "responses": { "200": { "description": "Das Ergebnis jeder Prüfung.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "latencyMs": { "type": "integer" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string" }, "ok": { "type": "boolean" } } } } } }, "example": { "ok": true, "latencyMs": 212, "checks": [ { "check": "authentication", "ok": true }, { "check": "tickets.write", "ok": true }, { "check": "documents.read", "ok": true } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts": { "get": { "operationId": "kontakte-auflisten", "summary": "Kontakte auflisten", "description": "Gibt Mieter, Eigentümer, Beiräte und Dienstleister zurück. Ist casavi, Facilioo oder DoNexus angebunden, kommen die Kontakte aus diesem System, und `source` nennt es.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "role", "in": "query", "required": false, "description": "Nur Kontakte mit dieser Rolle.", "schema": { "description": "Nur Kontakte mit dieser Rolle.", "type": "string", "enum": [ "tenant", "owner", "advisoryBoard", "serviceProvider", "prospect" ], "examples": [ "owner" ] } }, { "name": "building_id", "in": "query", "required": false, "description": "Nur Kontakte in diesem Objekt.", "schema": { "description": "Nur Kontakte in diesem Objekt.", "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Sucht in Name, Telefonnummer und E-Mail-Adresse.", "schema": { "description": "Sucht in Name, Telefonnummer und E-Mail-Adresse.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sortierung der Liste.", "schema": { "description": "Sortierung der Liste.", "type": "string", "enum": [ "name", "updated" ], "default": "name" } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Kontakten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "buildingId": { "type": "string" }, "unitIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "source": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "example": { "contacts": [ { "contactId": "ct_5Pz1rQ8", "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp.", "source": "geniefy", "updatedAt": "2026-08-30T12:00:00Z" } ], "total": 1308, "nextCursor": "eyJvIjoyMH0" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "kontakt-anlegen", "summary": "Kontakt anlegen", "description": "Legt einen Kontakt an. Nur verfügbar, wenn Geniefy die Kontakte selbst verwaltet.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Vollständiger Name.", "type": "string" }, "role": { "description": "Rolle des Kontakts.", "type": "string", "enum": [ "tenant", "owner", "advisoryBoard", "serviceProvider", "prospect" ] }, "phones": { "description": "Telefonnummern im Format E.164.", "type": "array", "items": { "type": "string" } }, "emails": { "description": "E-Mail-Adressen.", "type": "array", "items": { "type": "string" } }, "buildingId": { "description": "Objekt des Kontakts.", "type": "string" }, "unitIds": { "description": "Einheiten des Kontakts.", "type": "array", "items": { "type": "string" } }, "notes": { "description": "Interne Notiz, die der Agent kennt.", "type": "string" } }, "required": [ "name", "role" ] }, "example": { "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp." } } } }, "responses": { "201": { "description": "Der neue Kontakt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "buildingId": { "type": "string" }, "unitIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "source": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "contactId": "ct_5Pz1rQ8", "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp.", "source": "geniefy", "updatedAt": "2026-08-30T12:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Kontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/lookup": { "get": { "operationId": "lookup_contact", "summary": "Kontakt per Nummer finden", "description": "Findet Kontakte zu einer Telefonnummer, unabhängig von Schreibweise und Leerzeichen.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "x-mcp-tool": "lookup_contact", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Die Telefonnummer.", "schema": { "description": "Die Telefonnummer.", "type": "string", "examples": [ "+4915199990456" ] } } ], "responses": { "200": { "description": "Passende Kontakte, oft genau einer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "buildingId": { "type": "string" }, "unitIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "source": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "example": { "contacts": [ { "contactId": "ct_5Pz1rQ8", "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp.", "source": "geniefy", "updatedAt": "2026-08-30T12:00:00Z" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{contactId}": { "put": { "operationId": "kontakt-aendern", "summary": "Kontakt ändern", "description": "Ersetzt einen Kontakt vollständig.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "ID des Kontakts.", "schema": { "description": "ID des Kontakts.", "type": "string", "examples": [ "ct_5Pz1rQ8" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "buildingId": { "type": "string" }, "unitIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" } } }, "example": { "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp, tagsüber nicht erreichbar." } } } }, "responses": { "200": { "description": "Der geänderte Kontakt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "phones": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "buildingId": { "type": "string" }, "unitIds": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "source": { "type": "string" }, "updatedAt": { "type": "string" } } }, "example": { "contactId": "ct_5Pz1rQ8", "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ], "emails": [ "jonas.weber@example.de" ], "buildingId": "bld_Linden12", "unitIds": [ "unit_Linden12_WE04" ], "notes": "Bevorzugt WhatsApp, tagsüber nicht erreichbar.", "source": "geniefy", "updatedAt": "2026-08-30T12:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Kontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "kontakt-loeschen", "summary": "Kontakt löschen", "description": "Löscht einen Kontakt. Vergangene Anrufe bleiben erhalten.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "ID des Kontakts.", "schema": { "description": "ID des Kontakts.", "type": "string", "examples": [ "ct_5Pz1rQ8" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Kontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/import": { "post": { "operationId": "kontakte-importieren", "summary": "Kontakte importieren", "description": "Legt bis zu 1.000 Kontakte in einer Anfrage an oder aktualisiert sie. Ungültige Einträge werden übersprungen und in `errors` mit ihrer Position gemeldet.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "description": "Die Kontakte im Format von `POST /contacts`.", "type": "array", "items": { "type": "object" } } }, "required": [ "contacts" ] }, "example": { "contacts": [ { "name": "Jonas Weber", "role": "tenant", "phones": [ "+4915199990456" ] }, { "name": "Petra Lang", "role": "owner", "phones": [ "01519999" ] } ] } } } }, "responses": { "200": { "description": "Zusammenfassung des Imports.", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "imported": 1, "errors": [ { "index": 1, "code": "INVALID_PHONE", "field": "phones[0]", "message": "Phone number must be in E.164 format." } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/buildings": { "get": { "operationId": "objekte-auflisten", "summary": "Objekte auflisten", "description": "Gibt die verwalteten Objekte zurück.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Objekten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "buildings": { "type": "array", "items": { "type": "object", "properties": { "buildingId": { "type": "string" }, "label": { "type": "string" }, "address": { "type": "string" }, "type": { "type": "string" }, "unitCount": { "type": "integer" } } } }, "total": { "type": "integer" }, "nextCursor": { "type": "string" } } }, "example": { "buildings": [ { "buildingId": "bld_Linden12", "label": "Lindenstraße 12", "address": "Lindenstraße 12, 80331 München", "type": "weg", "unitCount": 24 } ], "total": 63, "nextCursor": "eyJvIjoyMH0" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/buildings/{buildingId}/units": { "get": { "operationId": "einheiten-auflisten", "summary": "Einheiten eines Objekts", "description": "Gibt Wohnungen, Gewerbeeinheiten und Stellplätze eines Objekts zurück.", "tags": [ "Kontakte und Objekte" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "buildingId", "in": "path", "required": true, "description": "ID des Objekts.", "schema": { "description": "ID des Objekts.", "type": "string", "examples": [ "bld_Linden12" ] } } ], "responses": { "200": { "description": "Die Einheiten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "units": { "type": "array", "items": { "type": "object", "properties": { "unitId": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "floor": { "type": "string" }, "areaSqm": { "type": "number" } } } } } }, "example": { "units": [ { "unitId": "unit_Linden12_WE04", "label": "WE 04", "type": "apartment", "floor": "1. OG", "areaSqm": 68.5 } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks": { "get": { "operationId": "list_tasks", "summary": "Aufgaben auflisten", "description": "Gibt Aufgaben zurück, die der Agent vorgeschlagen hat, etwa einen Vorgang anzulegen oder eine E-Mail an einen Dienstleister zu senden. Aufgaben mit `pending_review` warten auf Ihre Freigabe.", "tags": [ "Aufgaben" ], "security": [ { "bearerAuth": [ "tasks:read" ] } ], "x-scope": "tasks:read", "x-beta": true, "x-mcp-tool": "list_tasks", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Nur Aufgaben mit diesem Status.", "schema": { "description": "Nur Aufgaben mit diesem Status.", "type": "string", "enum": [ "pending_review", "approved", "rejected", "executed", "failed", "expired" ], "examples": [ "pending_review" ] } }, { "name": "type", "in": "query", "required": false, "description": "Nur Aufgaben dieses Typs.", "schema": { "description": "Nur Aufgaben dieses Typs.", "type": "string", "enum": [ "ticket.create", "email.outbound", "call.outbound" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Aufgaben.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "payload": { "type": "object", "properties": { "system": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "contractor": { "type": "string" } } }, "evidence": { "type": "object", "properties": { "callId": { "type": "string" }, "building": { "type": "string" }, "unit": { "type": "string" } } }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": {} } }, "example": { "tasks": [ { "taskId": "tsk_8Rv2Kq4", "type": "ticket.create", "status": "pending_review", "revision": 1, "payload": { "system": "casavi", "title": "Heizung im Bad ohne Funktion", "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.", "category": "Repairs", "priority": "normal", "contractor": "Heizungsbau Huber" }, "evidence": { "callId": "AJ_7tQm2KxV9pLr4", "building": "Lindenstraße 12", "unit": "WE 04" }, "expiresAt": "2026-09-17T08:28:30Z", "createdAt": "2026-09-14T08:29:05Z" } ], "total": 6, "nextCursor": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}": { "get": { "operationId": "aufgabe-abrufen", "summary": "Aufgabe abrufen", "description": "Gibt eine Aufgabe mit Vorschlag, Belegen und Verlauf zurück.", "tags": [ "Aufgaben" ], "security": [ { "bearerAuth": [ "tasks:read" ] } ], "x-scope": "tasks:read", "x-beta": true, "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "ID der Aufgabe.", "schema": { "description": "ID der Aufgabe.", "type": "string", "examples": [ "tsk_8Rv2Kq4" ] } } ], "responses": { "200": { "description": "Die Aufgabe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "payload": { "type": "object", "properties": { "system": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "contractor": { "type": "string" } } }, "evidence": { "type": "object", "properties": { "callId": { "type": "string" }, "building": { "type": "string" }, "unit": { "type": "string" } } }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "actor": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "example": { "taskId": "tsk_8Rv2Kq4", "type": "ticket.create", "status": "pending_review", "revision": 1, "payload": { "system": "casavi", "title": "Heizung im Bad ohne Funktion", "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.", "category": "Repairs", "priority": "normal", "contractor": "Heizungsbau Huber" }, "evidence": { "callId": "AJ_7tQm2KxV9pLr4", "building": "Lindenstraße 12", "unit": "WE 04" }, "expiresAt": "2026-09-17T08:28:30Z", "createdAt": "2026-09-14T08:29:05Z", "events": [ { "type": "proposed", "actor": "agent", "createdAt": "2026-09-14T08:29:05Z" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}/decision": { "post": { "operationId": "decide_task", "summary": "Aufgabe freigeben oder ablehnen", "description": "Gibt eine Aufgabe frei oder lehnt sie ab. Beim Freigeben können Sie einzelne Felder in `fields` korrigieren. Senden Sie `expectedRevision`, damit nicht zwei Personen dieselbe Aufgabe gleichzeitig entscheiden. Freigegebene Aufgaben werden sofort ausgeführt.", "tags": [ "Aufgaben" ], "security": [ { "bearerAuth": [ "tasks:write" ] } ], "x-scope": "tasks:write", "x-beta": true, "x-mcp-tool": "decide_task", "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "ID der Aufgabe.", "schema": { "description": "ID der Aufgabe.", "type": "string", "examples": [ "tsk_8Rv2Kq4" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "description": "Die Entscheidung.", "type": "string", "enum": [ "approve", "reject" ] }, "expectedRevision": { "description": "Die `revision`, die Sie zuletzt gesehen haben.", "type": "integer" }, "fields": { "description": "Korrigierte Felder des Vorschlags.", "type": "object" }, "reason": { "description": "Begründung bei einer Ablehnung.", "type": "string" } }, "required": [ "decision", "expectedRevision" ] }, "example": { "decision": "approve", "expectedRevision": 1, "fields": { "priority": "high" } } } } }, "responses": { "200": { "description": "Die entschiedene Aufgabe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "payload": { "type": "object", "properties": { "system": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "contractor": { "type": "string" } } }, "evidence": { "type": "object", "properties": { "callId": { "type": "string" }, "building": { "type": "string" }, "unit": { "type": "string" } } }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "execution": { "type": "object", "properties": { "result": { "type": "object", "properties": { "ticketId": { "type": "string" } } } } } } }, "example": { "taskId": "tsk_8Rv2Kq4", "type": "ticket.create", "status": "executed", "revision": 2, "payload": { "system": "casavi", "title": "Heizung im Bad ohne Funktion", "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.", "category": "Repairs", "priority": "high", "contractor": "Heizungsbau Huber" }, "evidence": { "callId": "AJ_7tQm2KxV9pLr4", "building": "Lindenstraße 12", "unit": "WE 04" }, "expiresAt": "2026-09-17T08:28:30Z", "createdAt": "2026-09-14T08:29:05Z", "execution": { "result": { "ticketId": "casavi:TK-20931" } } } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "REVISION_CONFLICT: Die Aufgabe wurde inzwischen von jemand anderem geändert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/summary": { "get": { "operationId": "get_insights_summary", "summary": "Zusammenfassung abrufen", "description": "Gibt die Kennzahlen eines Zeitraums zurück: Volumen je Kanal, Verteilung nach Kategorien und Wochentagen, Anteil außerhalb der Öffnungszeiten, angelegte Vorgänge und weitergeleitete Notfälle. Ohne Zeitraum gelten die letzten 30 Tage.", "tags": [ "Auswertungen" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "x-mcp-tool": "get_insights_summary", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-01" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-14" ] } }, { "name": "channel", "in": "query", "required": false, "description": "Nur diesen Kanal auswerten.", "schema": { "description": "Nur diesen Kanal auswerten.", "type": "string", "enum": [ "voice", "whatsapp", "email" ] } } ], "responses": { "200": { "description": "Die Kennzahlen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" } } }, "totals": { "type": "object", "properties": { "calls": { "type": "integer" }, "whatsappConversations": { "type": "integer" }, "emails": { "type": "integer" }, "callMinutes": { "type": "number" } } }, "byCategory": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "count": { "type": "integer" }, "share": { "type": "number" } } } }, "byWeekday": { "type": "object", "properties": { "monday": { "type": "integer" }, "tuesday": { "type": "integer" }, "wednesday": { "type": "integer" }, "thursday": { "type": "integer" }, "friday": { "type": "integer" }, "saturday": { "type": "integer" }, "sunday": { "type": "integer" } } }, "outsideOpeningHoursShare": { "type": "number" }, "ticketsCreated": { "type": "integer" }, "emergenciesForwarded": { "type": "object", "properties": { "total": { "type": "integer" }, "connected": { "type": "integer" } } }, "callbacksOpen": { "type": "integer" } } }, "example": { "period": { "startDate": "2026-09-01", "endDate": "2026-09-14" }, "totals": { "calls": 612, "whatsappConversations": 188, "emails": 243, "callMinutes": 1486.5 }, "byCategory": [ { "category": "Repairs", "count": 214, "share": 0.35 }, { "category": "Accounting", "count": 97, "share": 0.158 }, { "category": "Emergency", "count": 12, "share": 0.02 } ], "byWeekday": { "monday": 138, "tuesday": 121, "wednesday": 104, "thursday": 99, "friday": 96, "saturday": 31, "sunday": 23 }, "outsideOpeningHoursShare": 0.27, "ticketsCreated": 301, "emergenciesForwarded": { "total": 12, "connected": 11 }, "callbacksOpen": 9 } } } }, "400": { "description": "INVALID_DATE_FORMAT: Ein Datum hat nicht das Format `YYYY-MM-DD`. INVALID_DATE_RANGE: `start_date` liegt nach `end_date`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/buildings": { "get": { "operationId": "auswertung-objekte", "summary": "Auswertung nach Objekten", "description": "Zeigt, aus welchen Objekten und Einheiten die meisten Anfragen kommen und worum es geht.", "tags": [ "Auswertungen" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Erster Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "schema": { "description": "Letzter Tag des Zeitraums im Format `YYYY-MM-DD`, inklusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Objekte, meiste Anfragen zuerst.", "content": { "application/json": { "schema": { "type": "object", "properties": { "buildings": { "type": "array", "items": { "type": "object", "properties": { "buildingId": { "type": "string" }, "label": { "type": "string" }, "requests": { "type": "integer" }, "topCategory": { "type": "string" }, "topUnits": { "type": "array", "items": { "type": "object", "properties": { "unitId": { "type": "string" }, "label": { "type": "string" }, "requests": { "type": "integer" } } } } } } } } }, "example": { "buildings": [ { "buildingId": "bld_Linden12", "label": "Lindenstraße 12", "requests": 48, "topCategory": "Repairs", "topUnits": [ { "unitId": "unit_Linden12_WE04", "label": "WE 04", "requests": 9 } ] } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/categories/{category}": { "get": { "operationId": "auswertung-kategorie", "summary": "Verlauf einer Kategorie", "description": "Gibt die monatliche Entwicklung einer Kategorie und ihrer Unterkategorien zurück, etwa um steigende Reparaturthemen zu erkennen.", "tags": [ "Auswertungen" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Kategorie-Schlüssel aus `GET /categories`.", "schema": { "description": "Kategorie-Schlüssel aus `GET /categories`.", "type": "string", "examples": [ "Repairs" ] } }, { "name": "months", "in": "query", "required": false, "description": "Anzahl der Monate bis heute, höchstens 24.", "schema": { "description": "Anzahl der Monate bis heute, höchstens 24.", "type": "integer", "default": 6, "examples": [ 6 ] } } ], "responses": { "200": { "description": "Der Verlauf je Monat.", "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string" }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer" }, "subcategories": { "type": "object", "properties": { "Heating": { "type": "integer" }, "Plumbing": { "type": "integer" }, "WaterDamage": { "type": "integer" } } } } } } } }, "example": { "category": "Repairs", "months": [ { "month": "2026-08", "count": 402, "subcategories": { "Heating": 31, "Plumbing": 88, "WaterDamage": 40 } }, { "month": "2026-09", "count": 214, "subcategories": { "Heating": 44, "Plumbing": 39, "WaterDamage": 21 } } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/usage": { "get": { "operationId": "get_usage", "summary": "Verbrauch abrufen", "description": "Gibt Gesprächsminuten und WhatsApp-Sitzungen eines Monats zurück, dazu die voraussichtliche Summe netto.", "tags": [ "Abrechnung" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "x-mcp-tool": "get_usage", "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Monat im Format `YYYY-MM`, Standard ist der laufende Monat.", "schema": { "description": "Monat im Format `YYYY-MM`, Standard ist der laufende Monat.", "type": "string", "examples": [ "2026-09" ] } } ], "responses": { "200": { "description": "Der Verbrauch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "string" }, "plan": { "type": "string" }, "voice": { "type": "object", "properties": { "minutesIncluded": { "type": "integer" }, "minutesUsed": { "type": "number" }, "pricePerMinute": { "type": "number" }, "currency": { "type": "string" } } }, "whatsapp": { "type": "object", "properties": { "sessionsIncluded": { "type": "integer" }, "sessionsUsed": { "type": "integer" }, "pricePerExtraSession": { "type": "number" }, "currency": { "type": "string" } } }, "estimatedTotal": { "type": "object", "properties": { "net": { "type": "number" }, "currency": { "type": "string" } } } } }, "example": { "month": "2026-09", "plan": "plus", "voice": { "minutesIncluded": 200, "minutesUsed": 1486.5, "pricePerMinute": 0.5, "currency": "EUR" }, "whatsapp": { "sessionsIncluded": 150, "sessionsUsed": 188, "pricePerExtraSession": 0.4, "currency": "EUR" }, "estimatedTotal": { "net": 818.45, "currency": "EUR" } } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/details": { "get": { "operationId": "rechnungsdaten-abrufen", "summary": "Rechnungsdaten abrufen", "description": "Gibt Rechnungsanschrift, Rechnungs-E-Mail, Umsatzsteuer-ID und Zahlungsart zurück.", "tags": [ "Abrechnung" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "responses": { "200": { "description": "Die Rechnungsdaten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "type": "string" }, "billingEmail": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } }, "vatId": { "type": "string" }, "purchaseOrder": {}, "paymentMethod": { "type": "string" } } }, "example": { "companyName": "Hausverwaltung Muster GmbH", "billingEmail": "buchhaltung@hv-muster.de", "address": { "street": "Musterweg 3", "postalCode": "80331", "city": "München", "country": "DE" }, "vatId": "DE123456789", "purchaseOrder": null, "paymentMethod": "sepa_debit" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "rechnungsdaten-aendern", "summary": "Rechnungsdaten ändern", "description": "Ändert nur die Felder, die Sie mitsenden. Die Änderung gilt ab der nächsten Rechnung.", "tags": [ "Abrechnung" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "x-scope": "billing:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "description": "Firmenname auf der Rechnung.", "type": "string" }, "billingEmail": { "description": "Adresse, an die Rechnungen gehen.", "type": "string" }, "address": { "description": "Anschrift mit `street`, `postalCode`, `city` und `country`.", "type": "object" }, "vatId": { "description": "Umsatzsteuer-Identifikationsnummer.", "type": "string" }, "purchaseOrder": { "description": "Bestellnummer, die auf jeder Rechnung erscheint.", "type": "string" } } }, "example": { "billingEmail": "rechnungen@hv-muster.de", "purchaseOrder": "PO-2026-118" } } } }, "responses": { "200": { "description": "Die vollständigen Rechnungsdaten.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "type": "string" }, "billingEmail": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } }, "vatId": { "type": "string" }, "purchaseOrder": { "type": "string" }, "paymentMethod": { "type": "string" } } }, "example": { "companyName": "Hausverwaltung Muster GmbH", "billingEmail": "rechnungen@hv-muster.de", "address": { "street": "Musterweg 3", "postalCode": "80331", "city": "München", "country": "DE" }, "vatId": "DE123456789", "purchaseOrder": "PO-2026-118", "paymentMethod": "sepa_debit" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/invoices": { "get": { "operationId": "list_invoices", "summary": "Rechnungen auflisten", "description": "Gibt Ihre Rechnungen mit Link auf das PDF zurück, neueste zuerst.", "tags": [ "Abrechnung" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "x-mcp-tool": "list_invoices", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Rechnungen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "number": { "type": "string" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "total": { "type": "object", "properties": { "net": { "type": "number" }, "gross": { "type": "number" }, "currency": { "type": "string" } } }, "status": { "type": "string" }, "issuedAt": { "type": "string" }, "pdfUrl": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": {} } }, "example": { "invoices": [ { "invoiceId": "inv_2026_08", "number": "GF-2026-0812", "periodStart": "2026-08-01", "periodEnd": "2026-08-31", "total": { "net": 874.2, "gross": 1040.3, "currency": "EUR" }, "status": "paid", "issuedAt": "2026-09-01T06:00:00Z", "pdfUrl": "https://files.geniefy.de/inv/GF-2026-0812.pdf?sig=…" } ], "total": 5, "nextCursor": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems": { "get": { "operationId": "systeme-auflisten", "summary": "Verbundene Systeme auflisten", "description": "Gibt die angebundenen CRM-, ERP- und DMS-Systeme mit ihren verfügbaren Fähigkeiten zurück.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "responses": { "200": { "description": "Die Systeme.", "content": { "application/json": { "schema": { "type": "object", "properties": { "systems": { "type": "array", "items": { "type": "object", "properties": { "systemId": { "type": "string" }, "kind": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "systems": [ { "systemId": "casavi", "kind": [ "crm", "dms" ], "status": "connected", "capabilities": [ "tickets.read", "tickets.write", "documents.read", "units.read", "owners.read" ] }, { "systemId": "donexus", "kind": [ "erp" ], "status": "connected", "capabilities": [ "units.read", "tenants.read", "balances.read" ] } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/query": { "post": { "operationId": "query_systems", "summary": "Systeme in Sprache abfragen", "description": "Stellt eine Frage in natürlicher Sprache an alle angebundenen Systeme. Geniefy entscheidet, welche Systeme abgefragt werden, führt die Abfragen aus und gibt eine Antwort mit den gefundenen Datensätzen zurück. Jeder Datensatz nennt seine Quelle, damit Sie die Antwort prüfen können.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "x-mcp-tool": "query_systems", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "description": "Die Frage in ganzen Sätzen.", "type": "string" }, "systems": { "description": "Nur diese Systeme abfragen.", "type": "array", "items": { "type": "string" } }, "maxRecords": { "description": "Höchstzahl der zurückgegebenen Datensätze, Standard 20.", "type": "integer" } }, "required": [ "question" ] }, "example": { "question": "Welche offenen Vorgänge gibt es für die Lindenstraße 12, und wer ist jeweils zuständig?" } } } }, "responses": { "200": { "description": "Antwort mit Belegen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "assignee": { "type": "string" }, "source": { "type": "string" }, "appLink": { "type": "string" } } } }, "systemsQueried": { "type": "array", "items": { "type": "string" } } } }, "example": { "answer": "Für die Lindenstraße 12 sind zwei Vorgänge offen: TK-20931 (Heizung im Bad der WE 04, zuständig Maria Hoffmann) und TK-20874 (Aufzug bleibt zwischen den Etagen stehen, zuständig Tobias Brandt).", "records": [ { "type": "ticket", "id": "casavi:TK-20931", "title": "Heizung im Bad ohne Funktion", "status": "open", "assignee": "Maria Hoffmann", "source": "casavi", "appLink": "https://app.casavi.com/tickets/20931" }, { "type": "ticket", "id": "casavi:TK-20874", "title": "Aufzug bleibt zwischen den Etagen stehen", "status": "in_progress", "assignee": "Tobias Brandt", "source": "casavi", "appLink": "https://app.casavi.com/tickets/20874" } ], "systemsQueried": [ "casavi" ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/tickets": { "get": { "operationId": "list_tickets", "summary": "Vorgänge auflisten", "description": "Gibt Vorgänge aus allen angebundenen Systemen in einem einheitlichen Format zurück.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "x-mcp-tool": "list_tickets", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Nur Vorgänge mit diesem Status.", "schema": { "description": "Nur Vorgänge mit diesem Status.", "type": "string", "enum": [ "open", "in_progress", "done" ], "examples": [ "open" ] } }, { "name": "building_id", "in": "query", "required": false, "description": "Nur Vorgänge in diesem Objekt.", "schema": { "description": "Nur Vorgänge in diesem Objekt.", "type": "string", "examples": [ "bld_Linden12" ] } }, { "name": "unit_id", "in": "query", "required": false, "description": "Nur Vorgänge in dieser Einheit.", "schema": { "description": "Nur Vorgänge in dieser Einheit.", "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Sucht in Titel und Beschreibung.", "schema": { "description": "Sucht in Titel und Beschreibung.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "Der Wert `nextCursor` der vorherigen Seite.", "schema": { "description": "Der Wert `nextCursor` der vorherigen Seite.", "type": "string" } } ], "responses": { "200": { "description": "Eine Seite mit Vorgängen.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "items": { "type": "object", "properties": { "ticketId": { "type": "string" }, "system": { "type": "string" }, "displayNumber": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "buildingId": { "type": "string" }, "unitId": { "type": "string" }, "assignee": { "type": "string" }, "createdAt": { "type": "string" }, "appLink": { "type": "string" } } } }, "total": { "type": "integer" }, "nextCursor": {} } }, "example": { "tickets": [ { "ticketId": "casavi:TK-20931", "system": "casavi", "displayNumber": "TK-20931", "title": "Heizung im Bad ohne Funktion", "status": "open", "category": "Repairs", "priority": "normal", "buildingId": "bld_Linden12", "unitId": "unit_Linden12_WE04", "assignee": "Maria Hoffmann", "createdAt": "2026-09-14T08:29:40Z", "appLink": "https://app.casavi.com/tickets/20931" } ], "total": 2, "nextCursor": null } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_ticket", "summary": "Vorgang anlegen", "description": "Legt einen Vorgang im angebundenen System an und weist ihn optional zu. Ohne `system` wird das Hauptsystem Ihrer Verwaltung verwendet.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:write" ] } ], "x-scope": "systems:write", "x-beta": true, "x-mcp-tool": "create_ticket", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Verhindert doppelte Ausführung bei Wiederholungen.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Kurzer Titel.", "type": "string" }, "description": { "description": "Beschreibung des Anliegens.", "type": "string" }, "category": { "description": "Kategorie-Schlüssel aus `GET /categories`.", "type": "string" }, "buildingId": { "description": "Objekt.", "type": "string" }, "unitId": { "description": "Einheit.", "type": "string" }, "contactId": { "description": "Meldende Person.", "type": "string" }, "priority": { "description": "Dringlichkeit.", "type": "string", "enum": [ "low", "normal", "high", "emergency" ], "default": "normal" }, "assignee": { "description": "Zuständige Person im System.", "type": "string" }, "system": { "description": "Zielsystem, falls mehrere angebunden sind.", "type": "string" } }, "required": [ "title", "description" ] }, "example": { "title": "Heizung im Bad ohne Funktion", "description": "Heizkörper im Bad seit gestern kalt, übrige Räume warm.", "category": "Repairs", "buildingId": "bld_Linden12", "unitId": "unit_Linden12_WE04", "contactId": "ct_5Pz1rQ8", "priority": "normal", "assignee": "Maria Hoffmann" } } } }, "responses": { "201": { "description": "Der angelegte Vorgang.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketId": { "type": "string" }, "system": { "type": "string" }, "displayNumber": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "buildingId": { "type": "string" }, "unitId": { "type": "string" }, "assignee": { "type": "string" }, "createdAt": { "type": "string" }, "appLink": { "type": "string" } } }, "example": { "ticketId": "casavi:TK-20931", "system": "casavi", "displayNumber": "TK-20931", "title": "Heizung im Bad ohne Funktion", "status": "open", "category": "Repairs", "priority": "normal", "buildingId": "bld_Linden12", "unitId": "unit_Linden12_WE04", "assignee": "Maria Hoffmann", "createdAt": "2026-09-14T08:29:40Z", "appLink": "https://app.casavi.com/tickets/20931" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/tickets/{ticketId}": { "patch": { "operationId": "update_ticket", "summary": "Vorgang ändern", "description": "Ändert Status oder Zuständigkeit eines Vorgangs und fügt optional einen Kommentar hinzu.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:write" ] } ], "x-scope": "systems:write", "x-beta": true, "x-mcp-tool": "update_ticket", "parameters": [ { "name": "ticketId", "in": "path", "required": true, "description": "ID des Vorgangs.", "schema": { "description": "ID des Vorgangs.", "type": "string", "examples": [ "casavi:TK-20931" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Neuer Status.", "type": "string", "enum": [ "open", "in_progress", "done" ] }, "assignee": { "description": "Neue zuständige Person.", "type": "string" }, "comment": { "description": "Kommentar, der im System erscheint.", "type": "string" } } }, "example": { "status": "in_progress", "comment": "Heizungsbauer Huber kommt am 15.09. zwischen 8 und 10 Uhr." } } } }, "responses": { "200": { "description": "Der geänderte Vorgang.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticketId": { "type": "string" }, "system": { "type": "string" }, "displayNumber": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "buildingId": { "type": "string" }, "unitId": { "type": "string" }, "assignee": { "type": "string" }, "createdAt": { "type": "string" }, "appLink": { "type": "string" } } }, "example": { "ticketId": "casavi:TK-20931", "system": "casavi", "displayNumber": "TK-20931", "title": "Heizung im Bad ohne Funktion", "status": "in_progress", "category": "Repairs", "priority": "normal", "buildingId": "bld_Linden12", "unitId": "unit_Linden12_WE04", "assignee": "Maria Hoffmann", "createdAt": "2026-09-14T08:29:40Z", "appLink": "https://app.casavi.com/tickets/20931" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/documents": { "get": { "operationId": "find_documents", "summary": "Dokumente suchen", "description": "Findet Dokumente im angebundenen DMS, zum Beispiel Protokolle, Abrechnungen, Hausordnungen oder Beschlüsse. Der Download-Link ist 15 Minuten gültig.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "x-mcp-tool": "find_documents", "parameters": [ { "name": "building_id", "in": "query", "required": false, "description": "Nur Dokumente dieses Objekts.", "schema": { "description": "Nur Dokumente dieses Objekts.", "type": "string", "examples": [ "bld_Linden12" ] } }, { "name": "type", "in": "query", "required": false, "description": "Art des Dokuments.", "schema": { "description": "Art des Dokuments.", "type": "string", "enum": [ "meeting_minutes", "annual_statement", "operating_costs", "house_rules", "resolution", "contract", "other" ], "examples": [ "meeting_minutes" ] } }, { "name": "search", "in": "query", "required": false, "description": "Sucht in Titel und Inhalt.", "schema": { "description": "Sucht in Titel und Inhalt.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "schema": { "description": "Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf `total`.", "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Gefundene Dokumente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "date": { "type": "string" }, "buildingId": { "type": "string" }, "source": { "type": "string" }, "downloadUrl": { "type": "string" } } } } } }, "example": { "documents": [ { "documentId": "casavi:doc_77120", "title": "Protokoll Eigentümerversammlung 2026", "type": "meeting_minutes", "date": "2026-06-18", "buildingId": "bld_Linden12", "source": "casavi", "downloadUrl": "https://files.geniefy.de/dms/doc_77120.pdf?sig=…" } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/units/{unitId}": { "get": { "operationId": "einheit-im-system", "summary": "Einheit mit Beteiligten abrufen", "description": "Gibt eine Einheit mit Eigentümern, Mietern und, falls das ERP es liefert, dem aktuellen Hausgeldsaldo zurück.", "tags": [ "Verbundene Systeme" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "parameters": [ { "name": "unitId", "in": "path", "required": true, "description": "ID der Einheit.", "schema": { "description": "ID der Einheit.", "type": "string", "examples": [ "unit_Linden12_WE04" ] } } ], "responses": { "200": { "description": "Die Einheit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "unitId": { "type": "string" }, "label": { "type": "string" }, "buildingId": { "type": "string" }, "owners": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" } } } }, "tenants": { "type": "array", "items": { "type": "object", "properties": { "contactId": { "type": "string" }, "name": { "type": "string" }, "since": { "type": "string" }, "source": { "type": "string" } } } }, "balance": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" }, "asOf": { "type": "string" }, "source": { "type": "string" } } } } }, "example": { "unitId": "unit_Linden12_WE04", "label": "WE 04", "buildingId": "bld_Linden12", "owners": [ { "contactId": "ct_2Ow9", "name": "Petra Lang", "source": "donexus" } ], "tenants": [ { "contactId": "ct_5Pz1rQ8", "name": "Jonas Weber", "since": "2023-04-01", "source": "donexus" } ], "balance": { "amount": -412, "currency": "EUR", "asOf": "2026-09-13", "source": "donexus" } } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: Das angebundene System hat nicht oder fehlerhaft geantwortet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "post": { "operationId": "webhook-anlegen", "summary": "Webhook registrieren", "description": "Registriert eine HTTPS-Adresse für die gewählten Ereignisse. Das Geheimnis zur Signaturprüfung erhalten Sie nur in dieser Antwort, speichern Sie es sicher.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "x-scope": "webhooks:write", "x-beta": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "HTTPS-Adresse Ihres Servers.", "type": "string" }, "events": { "description": "Ereignisse, die zugestellt werden.", "type": "array", "items": { "type": "string" } }, "description": { "description": "Interne Beschreibung.", "type": "string" } }, "required": [ "url", "events" ] }, "example": { "url": "https://intranet.hv-muster.de/hooks/geniefy", "events": [ "call.completed", "ticket.created" ], "description": "Intranet Tagesübersicht" } } } }, "responses": { "201": { "description": "Der Webhook mit Geheimnis.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string" }, "createdAt": { "type": "string" } } }, "example": { "webhookId": "wh_3Nf8Pz", "url": "https://intranet.hv-muster.de/hooks/geniefy", "events": [ "call.completed", "ticket.created" ], "secret": "whsec_9c1f4b7e2a6d", "createdAt": "2026-09-14T11:00:00Z" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "webhooks-auflisten", "summary": "Webhooks auflisten", "description": "Gibt Ihre Webhooks mit dem Ergebnis der letzten Zustellung zurück.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "x-scope": "webhooks:write", "x-beta": true, "responses": { "200": { "description": "Die Webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "webhookId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "lastDelivery": { "type": "object", "properties": { "status": { "type": "integer" }, "at": { "type": "string" } } } } } } } }, "example": { "webhooks": [ { "webhookId": "wh_3Nf8Pz", "url": "https://intranet.hv-muster.de/hooks/geniefy", "events": [ "call.completed", "ticket.created" ], "lastDelivery": { "status": 200, "at": "2026-09-14T11:04:12Z" } } ] } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{webhookId}": { "delete": { "operationId": "webhook-loeschen", "summary": "Webhook entfernen", "description": "Entfernt einen Webhook. Laufende Zustellversuche werden abgebrochen.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "x-scope": "webhooks:write", "x-beta": true, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "ID des Webhooks.", "schema": { "description": "ID des Webhooks.", "type": "string", "examples": [ "wh_3Nf8Pz" ] } } ], "responses": { "204": { "description": "Keine Antwort im Körper." }, "401": { "description": "INVALID_TOKEN_FORMAT: Der Schlüssel hat kein gültiges Format. TOKEN_EXPIRED: Der Schlüssel ist abgelaufen oder wurde widerrufen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: Der Header `Authorization` fehlt oder enthält kein Bearer-Token. INSUFFICIENT_SCOPE: Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-Schlüssel, beginnt mit gfy_live_." } }, "schemas": { "Error": { "type": "object", "required": [ "code", "detail" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_DATE_FORMAT", "INVALID_DATE_RANGE", "INVALID_TOKEN_FORMAT", "TOKEN_EXPIRED", "MISSING_AUTHORIZATION", "INSUFFICIENT_SCOPE", "CALL_NOT_FOUND", "NOT_FOUND", "REVISION_CONFLICT", "VERSION_CONFLICT", "IDEMPOTENCY_CONFLICT", "CONVERSATION_NOT_TAKEN_OVER", "MANAGED_BY_CONNECTED_SYSTEM", "VALIDATION_ERROR", "RATE_LIMITED", "SERVER_ERROR", "SYSTEM_UNAVAILABLE" ] }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "x-mcp-server": "https://mcp.geniefy.de/v1" }