{ "openapi": "3.1.0", "info": { "title": "Geniefy API", "version": "1", "description": "The API of the AI operations layer for property management: calls, WhatsApp and email, knowledge, agent, forwarding, integrations, contacts, tasks, insights, billing and connected systems. The company is always derived from the API key.", "contact": { "name": "Geniefy", "email": "hello@geniefy.de", "url": "https://www.geniefy.de/developers" } }, "servers": [ { "url": "https://api.geniefy.de/v1" } ], "tags": [ { "name": "Calls", "description": "Every call your agent answers or places, with summary, classification, caller role and the tickets that came out of it. The list matches the call overview in the dashboard." }, { "name": "WhatsApp and email", "description": "Conversations from WhatsApp and the connected mailbox. You can read along, take conversations over, reply on behalf of your team and send emails or store them as drafts." }, { "name": "Knowledge", "description": "The questions and answers your agent relies on across every channel. A new entry applies immediately, there is no training time." }, { "name": "Procedures", "description": "Procedures tell the agent how to proceed in a specific situation, such as a lost key or a lease termination. In the dashboard they live under persona and procedures." }, { "name": "Agent", "description": "Your agent's name, voice, greeting, language and behaviour, plus blocked numbers. This matches the agent settings in the dashboard." }, { "name": "Forwarding", "description": "Opening hours, holidays and the rules by which calls are put through to your team, the advisory board or the emergency service." }, { "name": "Integrations", "description": "The connection to casavi, Facilioo or DoNexus and which features run through it." }, { "name": "Contacts and buildings", "description": "The people, buildings and units the agent uses to recognise callers and match requests." }, { "name": "Tasks", "description": "When an action needs human approval, the agent proposes it as a task. You review the proposal, correct it if needed and approve it.", "x-beta": true }, { "name": "Insights", "description": "The figures from the insights area of the dashboard: volume, topics, buildings and trends over time." }, { "name": "Billing", "description": "Current month usage, billing details and invoices as PDF." }, { "name": "Connected systems", "description": "Geniefy sits as an operations layer on top of your company's CRM, ERP and DMS. These endpoints reach the connected systems through Geniefy: in one consistent format, whether the data comes from casavi, Facilioo or DoNexus.", "x-beta": true }, { "name": "Webhooks", "description": "Register addresses Geniefy sends events to. How to verify deliveries is described under receiving webhooks.", "x-beta": true } ], "paths": { "/calls": { "get": { "operationId": "search_calls", "summary": "List calls", "description": "Returns your company's calls, newest first. All filters can be combined. If you pass category and subcategory together, both must belong to the same classification. When a filter only matches a secondary category, the card carries a `matchedOn` field.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "search_calls", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "category", "in": "query", "required": false, "description": "One or more categories, comma separated. Multiple values are combined with OR.", "schema": { "description": "One or more categories, comma separated. Multiple values are combined with OR.", "type": "string", "examples": [ "Repairs" ] } }, { "name": "subcategory", "in": "query", "required": false, "description": "One or more subcategories, comma separated. Multiple values are combined with OR.", "schema": { "description": "One or more subcategories, comma separated. Multiple values are combined with OR.", "type": "string", "examples": [ "Heating,HotWater" ] } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive search across name, topic and call id. If the search contains only digits, the phone number is searched as well.", "schema": { "description": "Case-insensitive search across name, topic and call id. If the search contains only digits, the phone number is searched as well.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20, "examples": [ 20 ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of call cards.", "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: A date is not in `YYYY-MM-DD` format. INVALID_DATE_RANGE: `start_date` is after `end_date`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{callId}": { "get": { "operationId": "get_call", "summary": "Retrieve a call", "description": "Returns one call with summary, caller role, address, created tickets and forwarding. An unknown id and another company's id both return `404 CALL_NOT_FOUND`. Retrieving a call does not mark it as read.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "get_call", "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Id from a call card.", "schema": { "description": "Id from a call card.", "type": "string", "examples": [ "AJ_7tQm2KxV9pLr4" ] } } ], "responses": { "200": { "description": "The full call object.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CALL_NOT_FOUND: There is no call with this id in your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/{callId}/transcript": { "get": { "operationId": "get_call_transcript", "summary": "Retrieve a transcript", "description": "Returns the conversation as a sequence of turns. Each turn names the speaker and its offset in milliseconds from the start of the call.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "get_call_transcript", "parameters": [ { "name": "callId", "in": "path", "required": true, "description": "Id of the call.", "schema": { "description": "Id of the call.", "type": "string", "examples": [ "AJ_7tQm2KxV9pLr4" ] } } ], "responses": { "200": { "description": "The call transcript.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CALL_NOT_FOUND: There is no call with this id in your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/calls/outbound": { "post": { "operationId": "start_outbound_call", "summary": "Start an outbound call", "description": "The agent calls a person, for example to return a call or to follow up with a contractor. The instruction describes what the agent should achieve. Without `scheduledAt` the call starts within a minute. The result then appears as a regular call and through the `call.completed` event.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [ "calls:write" ] } ], "x-scope": "calls:write", "x-mcp-tool": "start_outbound_call", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "description": "Phone number in E.164 format.", "type": "string" }, "instruction": { "description": "What the agent should settle during the call, in full sentences.", "type": "string" }, "contactId": { "description": "Links the call to a contact.", "type": "string" }, "relatedCallId": { "description": "The call this callback refers to.", "type": "string" }, "language": { "description": "Call language, defaults to the agent's primary language.", "type": "string", "enum": [ "de", "en" ] }, "scheduledAt": { "description": "Time in ISO 8601, no earlier than now and at most seven days ahead.", "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": "The call has been queued.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/categories": { "get": { "operationId": "list_categories", "summary": "List categories", "description": "Returns the categories and subcategories your requests are classified into. Call this endpoint before filtering, because the values are exact and depend on the channel.", "tags": [ "Calls" ], "security": [ { "bearerAuth": [ "calls:read" ] } ], "x-scope": "calls:read", "x-mcp-tool": "list_categories", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Channel whose vocabulary is returned.", "schema": { "description": "Channel whose vocabulary is returned.", "type": "string", "enum": [ "voice", "whatsapp", "email" ], "default": "voice", "examples": [ "voice" ] } } ], "responses": { "200": { "description": "The classification vocabulary.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations": { "get": { "operationId": "list_conversations", "summary": "List conversations", "description": "Returns WhatsApp and email threads, most recently active first.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "x-mcp-tool": "list_conversations", "parameters": [ { "name": "channel", "in": "query", "required": false, "description": "Only conversations on this channel.", "schema": { "description": "Only conversations on this channel.", "type": "string", "enum": [ "whatsapp", "email" ], "examples": [ "whatsapp" ] } }, { "name": "status", "in": "query", "required": false, "description": "Only open or only closed conversations.", "schema": { "description": "Only open or only closed conversations.", "type": "string", "enum": [ "open", "closed" ] } }, { "name": "mode", "in": "query", "required": false, "description": "Only conversations currently handled by the agent or by a person.", "schema": { "description": "Only conversations currently handled by the agent or by a person.", "type": "string", "enum": [ "ai", "human" ] } }, { "name": "start_date", "in": "query", "required": false, "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "search", "in": "query", "required": false, "description": "Searches name, phone number, email address and subject.", "schema": { "description": "Searches name, phone number, email address and subject.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of conversations.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}": { "get": { "operationId": "get_conversation", "summary": "Retrieve a conversation", "description": "Returns one conversation with all messages and attachments. Attachments such as photos or voice notes come as signed links.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "x-mcp-tool": "get_conversation", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Id of the conversation.", "schema": { "description": "Id of the conversation.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } } ], "responses": { "200": { "description": "The conversation with messages.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/live": { "get": { "operationId": "live-gespraeche", "summary": "List live conversations", "description": "Returns the WhatsApp conversations with activity in the last 15 minutes. This matches the WhatsApp live view in the dashboard and suits your own control room screens.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:read" ] } ], "x-scope": "conversations:read", "responses": { "200": { "description": "The active conversations.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}/messages": { "post": { "operationId": "send_message", "summary": "Send a message", "description": "Sends a message on behalf of your team. On WhatsApp the conversation must be taken over first (`mode` is `human`), so the agent and a person don't reply at the same time. Outside WhatsApp's 24 hour window only an approved template can be sent.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "send_message", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Id of the conversation.", "schema": { "description": "Id of the conversation.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "Message content, at most 4,096 characters.", "type": "string" }, "attachments": { "description": "Up to five attachments with `type` and a publicly reachable `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": "The sent message.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "CONVERSATION_NOT_TAKEN_OVER: The conversation must be taken over before sending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conversations/{conversationId}/mode": { "put": { "operationId": "set_conversation_mode", "summary": "Take over or hand back", "description": "With `human` your team takes over and the agent stays silent. With `ai` you hand it back to the agent, which knows the history so far and continues from there.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "set_conversation_mode", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "description": "Id of the conversation.", "schema": { "description": "Id of the conversation.", "type": "string", "examples": [ "wa_9KfR2mXq71" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "description": "Who handles the conversation.", "type": "string", "enum": [ "ai", "human" ] } }, "required": [ "mode" ] }, "example": { "mode": "human" } } } }, "responses": { "200": { "description": "The updated conversation.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/emails": { "post": { "operationId": "send_email", "summary": "Send an email", "description": "Sends an email through the connected mailbox or stores it as a draft for review. With `conversationId` the email is filed as a reply in the existing thread.", "tags": [ "WhatsApp and email" ], "security": [ { "bearerAuth": [ "conversations:write" ] } ], "x-scope": "conversations:write", "x-mcp-tool": "send_email", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "description": "Recipient addresses.", "type": "array", "items": { "type": "string" } }, "cc": { "description": "Addresses in copy.", "type": "array", "items": { "type": "string" } }, "subject": { "description": "Email subject.", "type": "string" }, "text": { "description": "Body as plain text. Separate paragraphs with a blank line.", "type": "string" }, "conversationId": { "description": "Thread in which the email appears as a reply.", "type": "string" }, "sendMode": { "description": "Send right away or store as a draft.", "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": "The email or draft.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs": { "get": { "operationId": "faqs-auflisten", "summary": "List FAQs", "description": "Returns every question and answer your agent knows.", "tags": [ "Knowledge" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of 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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_faq", "summary": "Create an FAQ", "description": "Creates an entry the agent uses on every channel right away. If the question closely resembles an existing entry, it is still created and the response contains `duplicateWarning` with the similar entry.", "tags": [ "Knowledge" ], "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": "The question, the way callers would ask it.", "type": "string" }, "answer": { "description": "The answer in full sentences.", "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": "The new entry.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs/search": { "get": { "operationId": "search_knowledge", "summary": "Search FAQs", "description": "Finds entries by meaning, not only by wording. A search for utility costs also finds an answer that talks about service charges.", "tags": [ "Knowledge" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "x-mcp-tool": "search_knowledge", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Question or keyword.", "schema": { "description": "Question or keyword.", "type": "string", "examples": [ "Nebenkostenabrechnung" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Matches, best match first.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/faqs/{faqId}": { "get": { "operationId": "faq-abrufen", "summary": "Retrieve an FAQ", "description": "Returns a single entry.", "tags": [ "Knowledge" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "Id of the entry.", "schema": { "description": "Id of the entry.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "responses": { "200": { "description": "The entry.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update_faq", "summary": "Update an FAQ", "description": "Replaces the question and answer of an entry.", "tags": [ "Knowledge" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "x-mcp-tool": "update_faq", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "Id of the entry.", "schema": { "description": "Id of the entry.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "description": "The new question.", "type": "string" }, "answer": { "description": "The new answer.", "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": "The updated entry.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "faq-loeschen", "summary": "Delete an FAQ", "description": "Deletes an entry. The agent stops using it immediately.", "tags": [ "Knowledge" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "faqId", "in": "path", "required": true, "description": "Id of the entry.", "schema": { "description": "Id of the entry.", "type": "string", "examples": [ "faq_3Hc8wQ2p" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/procedures": { "get": { "operationId": "list_procedures", "summary": "List procedures", "description": "Returns every procedure the agent follows in specific situations.", "tags": [ "Procedures" ], "security": [ { "bearerAuth": [ "knowledge:read" ] } ], "x-scope": "knowledge:read", "x-mcp-tool": "list_procedures", "responses": { "200": { "description": "All procedures.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "ablauf-anlegen", "summary": "Create a procedure", "description": "Creates a procedure. `trigger` describes in one sentence when it applies, `steps` tells the agent what to do, step by step.", "tags": [ "Procedures" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Short name shown in the dashboard.", "type": "string" }, "trigger": { "description": "Situation in which the procedure applies.", "type": "string" }, "steps": { "description": "The steps in order.", "type": "array", "items": { "type": "string" } }, "channels": { "description": "Channels where the procedure applies. Defaults to all.", "type": "array", "items": { "type": "string", "enum": [ "voice", "whatsapp", "email" ] } }, "enabled": { "description": "Whether the procedure is active.", "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": "The new procedure.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/procedures/{procedureId}": { "put": { "operationId": "ablauf-aendern", "summary": "Update a procedure", "description": "Replaces a procedure completely.", "tags": [ "Procedures" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "procedureId", "in": "path", "required": true, "description": "Id of the procedure.", "schema": { "description": "Id of the procedure.", "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": "The updated procedure.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "ablauf-loeschen", "summary": "Delete a procedure", "description": "Deletes a procedure.", "tags": [ "Procedures" ], "security": [ { "bearerAuth": [ "knowledge:write" ] } ], "x-scope": "knowledge:write", "parameters": [ { "name": "procedureId", "in": "path", "required": true, "description": "Id of the procedure.", "schema": { "description": "Id of the procedure.", "type": "string", "examples": [ "prc_W4n7Lx1" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/settings": { "get": { "operationId": "get_agent_settings", "summary": "Retrieve agent settings", "description": "Returns your agent's name, voice, greeting and behaviour.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "x-mcp-tool": "get_agent_settings", "responses": { "200": { "description": "The current settings.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_agent_settings", "summary": "Update agent settings", "description": "Changes only the fields you send. Changes apply from the next call or message.", "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 the agent introduces itself with.", "type": "string" }, "voiceId": { "description": "Voice from `GET /agent/voices`.", "type": "string" }, "greeting": { "description": "Greeting per language with the keys `de` and `en`.", "type": "object" }, "primaryLanguage": { "description": "Language conversations start in.", "type": "string", "enum": [ "de", "en" ] }, "callRecordingConsent": { "description": "Whether the agent asks for recording consent at the start.", "type": "boolean" }, "notificationEmail": { "description": "Address for summaries and notices.", "type": "string" }, "fallbackPhone": { "description": "Number calls are put through to during an outage.", "type": "string" }, "voiceSpeed": { "description": "Speaking rate between 0.8 and 1.2.", "type": "number" }, "pronunciations": { "description": "Words with pronunciation, each with `word` and `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": "The full, updated settings.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/voices": { "get": { "operationId": "stimmen-auflisten", "summary": "List voices", "description": "Returns the available voices with a short audio sample.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "parameters": [ { "name": "language", "in": "query", "required": false, "description": "Only voices for this language.", "schema": { "description": "Only voices for this language.", "type": "string", "enum": [ "de", "en" ], "examples": [ "de" ] } } ], "responses": { "200": { "description": "The voices.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/voices/preview": { "post": { "operationId": "stimme-probehoeren", "summary": "Preview a voice", "description": "Creates an audio sample with your own text, for example to check a new greeting.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "description": "Text, at most 500 characters.", "type": "string" }, "voiceId": { "description": "The voice.", "type": "string" }, "voiceSpeed": { "description": "Speaking rate between 0.8 and 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": "A link to the audio file.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/blocked-numbers": { "get": { "operationId": "gesperrte-nummern", "summary": "List blocked numbers", "description": "Returns the numbers whose calls and messages the agent does not accept.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:read" ] } ], "x-scope": "agent:read", "responses": { "200": { "description": "The blocked numbers.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "block_number", "summary": "Block a number", "description": "Blocks a number for calls and 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": "Number in E.164 format.", "type": "string" }, "reason": { "description": "Internal reason, visible in the dashboard.", "type": "string" } }, "required": [ "phone" ] }, "example": { "phone": "+4930555000111", "reason": "Werbeanrufe" } } } }, "responses": { "201": { "description": "The entry.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agent/blocked-numbers/{phone}": { "delete": { "operationId": "nummer-entsperren", "summary": "Unblock a number", "description": "Removes the block on a number.", "tags": [ "Agent" ], "security": [ { "bearerAuth": [ "agent:write" ] } ], "x-scope": "agent:write", "parameters": [ { "name": "phone", "in": "path", "required": true, "description": "Number in E.164 format.", "schema": { "description": "Number in E.164 format.", "type": "string", "examples": [ "+4930555000111" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding": { "get": { "operationId": "get_forwarding", "summary": "Retrieve forwarding", "description": "Returns opening hours, holiday handling and every forwarding rule.", "tags": [ "Forwarding" ], "security": [ { "bearerAuth": [ "forwarding:read" ] } ], "x-scope": "forwarding:read", "x-mcp-tool": "get_forwarding", "responses": { "200": { "description": "The configuration.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "weiterleitung-ersetzen", "summary": "Replace forwarding", "description": "Replaces the whole configuration. Send the `version` you last read. If the configuration has changed in the meantime, the API answers with `409 VERSION_CONFLICT` and nothing is overwritten.", "tags": [ "Forwarding" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "description": "Last version you read.", "type": "integer" }, "openingHours": { "description": "Opening hours per weekday with `open`, `from` and `to`.", "type": "object" }, "holidays": { "description": "Federal state as `region` and whether you are closed on holidays.", "type": "object" }, "rules": { "description": "At most 40 rules. Rules are evaluated top to bottom.", "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": "The saved configuration.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "VERSION_CONFLICT: The configuration changed since you last read it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding/rules": { "post": { "operationId": "regel-anlegen", "summary": "Create a forwarding rule", "description": "Appends a rule to the list. `kind` sets the type: `role` forwards by role and request, `vip` always puts certain numbers through, `pin` puts callers through after they enter a PIN.", "tags": [ "Forwarding" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "Type of rule.", "type": "string", "enum": [ "role", "vip", "pin" ] }, "target": { "description": "Target number in E.164 format.", "type": "string" }, "window": { "description": "When the rule applies.", "type": "string", "enum": [ "always", "openingHours", "outsideOpeningHours" ], "default": "always" }, "roles": { "description": "For `role`: roles the rule applies to.", "type": "array", "items": { "type": "string" } }, "trigger": { "description": "For `role`: `any` or `emergency`.", "type": "string" }, "callers": { "description": "For `vip`: up to 50 numbers.", "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "target" ] }, "example": { "kind": "role", "roles": [ "serviceProvider" ], "trigger": "any", "target": "+498912345672", "window": "openingHours" } } } }, "responses": { "201": { "description": "The new rule.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/forwarding/rules/{ruleId}": { "delete": { "operationId": "regel-loeschen", "summary": "Delete a forwarding rule", "description": "Removes a rule.", "tags": [ "Forwarding" ], "security": [ { "bearerAuth": [ "forwarding:write" ] } ], "x-scope": "forwarding:write", "parameters": [ { "name": "ruleId", "in": "path", "required": true, "description": "Id of the rule.", "schema": { "description": "Id of the rule.", "type": "string", "examples": [ "rl_Svc4" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations": { "get": { "operationId": "integration-abrufen", "summary": "Retrieve the integration", "description": "Returns which system Geniefy is connected to and which features are active.", "tags": [ "Integrations" ], "security": [ { "bearerAuth": [ "integrations:read" ] } ], "x-scope": "integrations:read", "responses": { "200": { "description": "The integration.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "integration-aendern", "summary": "Configure the integration", "description": "Sets the system and the active features. Credentials are stored encrypted and never returned. With `geniefy`, Geniefy manages contacts and tickets itself.", "tags": [ "Integrations" ], "security": [ { "bearerAuth": [ "integrations:write" ] } ], "x-scope": "integrations:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationType": { "description": "The connected system.", "type": "string", "enum": [ "geniefy", "casavi", "facilioo", "donexus" ] }, "features": { "description": "Features to switch on or off.", "type": "object" }, "credentials": { "description": "Credentials for the system, for example an API token.", "type": "object" } }, "required": [ "integrationType" ] }, "example": { "integrationType": "casavi", "features": { "createTickets": true, "lookupDocuments": true }, "credentials": { "apiToken": "cas_…" } } } } }, "responses": { "200": { "description": "The saved integration.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations/test": { "post": { "operationId": "integration-testen", "summary": "Test the integration", "description": "Checks connection and permissions without changing any data.", "tags": [ "Integrations" ], "security": [ { "bearerAuth": [ "integrations:write" ] } ], "x-scope": "integrations:write", "responses": { "200": { "description": "The result of each check.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts": { "get": { "operationId": "kontakte-auflisten", "summary": "List contacts", "description": "Returns tenants, owners, advisory board members and contractors. If casavi, Facilioo or DoNexus is connected, contacts come from that system and `source` names it.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "role", "in": "query", "required": false, "description": "Only contacts with this role.", "schema": { "description": "Only contacts with this role.", "type": "string", "enum": [ "tenant", "owner", "advisoryBoard", "serviceProvider", "prospect" ], "examples": [ "owner" ] } }, { "name": "building_id", "in": "query", "required": false, "description": "Only contacts in this building.", "schema": { "description": "Only contacts in this building.", "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Searches name, phone number and email address.", "schema": { "description": "Searches name, phone number and email address.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order of the list.", "schema": { "description": "Sort order of the list.", "type": "string", "enum": [ "name", "updated" ], "default": "name" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of contacts.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "kontakt-anlegen", "summary": "Create a contact", "description": "Creates a contact. Only available when Geniefy manages contacts itself.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Full name.", "type": "string" }, "role": { "description": "Role of the contact.", "type": "string", "enum": [ "tenant", "owner", "advisoryBoard", "serviceProvider", "prospect" ] }, "phones": { "description": "Phone numbers in E.164 format.", "type": "array", "items": { "type": "string" } }, "emails": { "description": "Email addresses.", "type": "array", "items": { "type": "string" } }, "buildingId": { "description": "Building of the contact.", "type": "string" }, "unitIds": { "description": "Units of the contact.", "type": "array", "items": { "type": "string" } }, "notes": { "description": "Internal note the agent knows about.", "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": "The new contact.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Contacts are maintained in the connected system and can't be changed here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/lookup": { "get": { "operationId": "lookup_contact", "summary": "Look up a contact by number", "description": "Finds contacts for a phone number, regardless of formatting and spaces.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "x-mcp-tool": "lookup_contact", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "The phone number.", "schema": { "description": "The phone number.", "type": "string", "examples": [ "+4915199990456" ] } } ], "responses": { "200": { "description": "Matching contacts, usually exactly one.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{contactId}": { "put": { "operationId": "kontakt-aendern", "summary": "Update a contact", "description": "Replaces a contact completely.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Id of the contact.", "schema": { "description": "Id of the contact.", "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": "The updated contact.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Contacts are maintained in the connected system and can't be changed here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "kontakt-loeschen", "summary": "Delete a contact", "description": "Deletes a contact. Past calls are kept.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "contactId", "in": "path", "required": true, "description": "Id of the contact.", "schema": { "description": "Id of the contact.", "type": "string", "examples": [ "ct_5Pz1rQ8" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "MANAGED_BY_CONNECTED_SYSTEM: Contacts are maintained in the connected system and can't be changed here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/import": { "post": { "operationId": "kontakte-importieren", "summary": "Import contacts", "description": "Creates or updates up to 1,000 contacts in one request. Invalid entries are skipped and reported in `errors` with their position.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:write" ] } ], "x-scope": "contacts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "description": "The contacts in the format of `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": "Import summary.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/buildings": { "get": { "operationId": "objekte-auflisten", "summary": "List buildings", "description": "Returns the managed buildings.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of buildings.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/buildings/{buildingId}/units": { "get": { "operationId": "einheiten-auflisten", "summary": "List units of a building", "description": "Returns the apartments, commercial units and parking spaces of a building.", "tags": [ "Contacts and buildings" ], "security": [ { "bearerAuth": [ "contacts:read" ] } ], "x-scope": "contacts:read", "parameters": [ { "name": "buildingId", "in": "path", "required": true, "description": "Id of the building.", "schema": { "description": "Id of the building.", "type": "string", "examples": [ "bld_Linden12" ] } } ], "responses": { "200": { "description": "The units.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks": { "get": { "operationId": "list_tasks", "summary": "List tasks", "description": "Returns tasks the agent has proposed, such as creating a ticket or emailing a contractor. Tasks with `pending_review` are waiting for your approval.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [ "tasks:read" ] } ], "x-scope": "tasks:read", "x-beta": true, "x-mcp-tool": "list_tasks", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only tasks with this status.", "schema": { "description": "Only tasks with this status.", "type": "string", "enum": [ "pending_review", "approved", "rejected", "executed", "failed", "expired" ], "examples": [ "pending_review" ] } }, { "name": "type", "in": "query", "required": false, "description": "Only tasks of this type.", "schema": { "description": "Only tasks of this type.", "type": "string", "enum": [ "ticket.create", "email.outbound", "call.outbound" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of tasks.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}": { "get": { "operationId": "aufgabe-abrufen", "summary": "Retrieve a task", "description": "Returns a task with its proposal, evidence and history.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [ "tasks:read" ] } ], "x-scope": "tasks:read", "x-beta": true, "parameters": [ { "name": "taskId", "in": "path", "required": true, "description": "Id of the task.", "schema": { "description": "Id of the task.", "type": "string", "examples": [ "tsk_8Rv2Kq4" ] } } ], "responses": { "200": { "description": "The task.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tasks/{taskId}/decision": { "post": { "operationId": "decide_task", "summary": "Approve or reject a task", "description": "Approves or rejects a task. When approving you can correct individual fields in `fields`. Send `expectedRevision` so two people can't decide the same task at once. Approved tasks are executed right away.", "tags": [ "Tasks" ], "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 of the task.", "schema": { "description": "Id of the task.", "type": "string", "examples": [ "tsk_8Rv2Kq4" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "description": "The decision.", "type": "string", "enum": [ "approve", "reject" ] }, "expectedRevision": { "description": "The `revision` you last saw.", "type": "integer" }, "fields": { "description": "Corrected fields of the proposal.", "type": "object" }, "reason": { "description": "Reason when rejecting.", "type": "string" } }, "required": [ "decision", "expectedRevision" ] }, "example": { "decision": "approve", "expectedRevision": 1, "fields": { "priority": "high" } } } } }, "responses": { "200": { "description": "The decided task.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "REVISION_CONFLICT: Someone else changed the task in the meantime.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/summary": { "get": { "operationId": "get_insights_summary", "summary": "Retrieve a summary", "description": "Returns the key figures for a period: volume per channel, distribution by category and weekday, share outside opening hours, created tickets and forwarded emergencies. Without a period the last 30 days apply.", "tags": [ "Insights" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "x-mcp-tool": "get_insights_summary", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-01" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-14" ] } }, { "name": "channel", "in": "query", "required": false, "description": "Only analyse this channel.", "schema": { "description": "Only analyse this channel.", "type": "string", "enum": [ "voice", "whatsapp", "email" ] } } ], "responses": { "200": { "description": "The key figures.", "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: A date is not in `YYYY-MM-DD` format. INVALID_DATE_RANGE: `start_date` is after `end_date`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/buildings": { "get": { "operationId": "auswertung-objekte", "summary": "Insights by building", "description": "Shows which buildings and units send the most requests and what they are about.", "tags": [ "Insights" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "parameters": [ { "name": "start_date", "in": "query", "required": false, "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "First day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-07" ] } }, { "name": "end_date", "in": "query", "required": false, "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "schema": { "description": "Last day of the period as `YYYY-MM-DD`, inclusive.", "type": "string", "examples": [ "2026-09-13" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "Buildings, most requests first.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/categories/{category}": { "get": { "operationId": "auswertung-kategorie", "summary": "Trend of a category", "description": "Returns the monthly trend of a category and its subcategories, for example to spot rising repair topics.", "tags": [ "Insights" ], "security": [ { "bearerAuth": [ "insights:read" ] } ], "x-scope": "insights:read", "parameters": [ { "name": "category", "in": "path", "required": true, "description": "Category key from `GET /categories`.", "schema": { "description": "Category key from `GET /categories`.", "type": "string", "examples": [ "Repairs" ] } }, { "name": "months", "in": "query", "required": false, "description": "Number of months up to today, at most 24.", "schema": { "description": "Number of months up to today, at most 24.", "type": "integer", "default": 6, "examples": [ 6 ] } } ], "responses": { "200": { "description": "The trend per month.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/usage": { "get": { "operationId": "get_usage", "summary": "Retrieve usage", "description": "Returns call minutes and WhatsApp sessions for a month, plus the expected net total.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "x-mcp-tool": "get_usage", "parameters": [ { "name": "month", "in": "query", "required": false, "description": "Month as `YYYY-MM`, defaults to the current month.", "schema": { "description": "Month as `YYYY-MM`, defaults to the current month.", "type": "string", "examples": [ "2026-09" ] } } ], "responses": { "200": { "description": "The usage.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/details": { "get": { "operationId": "rechnungsdaten-abrufen", "summary": "Retrieve billing details", "description": "Returns billing address, billing email, VAT id and payment method.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "responses": { "200": { "description": "The billing details.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "rechnungsdaten-aendern", "summary": "Update billing details", "description": "Changes only the fields you send. The change applies from the next invoice.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:write" ] } ], "x-scope": "billing:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "companyName": { "description": "Company name on the invoice.", "type": "string" }, "billingEmail": { "description": "Address invoices are sent to.", "type": "string" }, "address": { "description": "Address with `street`, `postalCode`, `city` and `country`.", "type": "object" }, "vatId": { "description": "VAT identification number.", "type": "string" }, "purchaseOrder": { "description": "Purchase order number printed on every invoice.", "type": "string" } } }, "example": { "billingEmail": "rechnungen@hv-muster.de", "purchaseOrder": "PO-2026-118" } } } }, "responses": { "200": { "description": "The full billing details.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing/invoices": { "get": { "operationId": "list_invoices", "summary": "List invoices", "description": "Returns your invoices with a link to the PDF, newest first.", "tags": [ "Billing" ], "security": [ { "bearerAuth": [ "billing:read" ] } ], "x-scope": "billing:read", "x-mcp-tool": "list_invoices", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of invoices.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems": { "get": { "operationId": "systeme-auflisten", "summary": "List connected systems", "description": "Returns the connected CRM, ERP and DMS systems with their available capabilities.", "tags": [ "Connected systems" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "responses": { "200": { "description": "The systems.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/query": { "post": { "operationId": "query_systems", "summary": "Query systems in plain language", "description": "Asks all connected systems a question in natural language. Geniefy decides which systems to query, runs the queries and returns an answer with the records it found. Every record names its source, so you can check the answer.", "tags": [ "Connected systems" ], "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": "The question in full sentences.", "type": "string" }, "systems": { "description": "Only query these systems.", "type": "array", "items": { "type": "string" } }, "maxRecords": { "description": "Maximum number of records returned, default 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": "Answer with evidence.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/tickets": { "get": { "operationId": "list_tickets", "summary": "List tickets", "description": "Returns tickets from every connected system in one consistent format.", "tags": [ "Connected systems" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "x-mcp-tool": "list_tickets", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only tickets with this status.", "schema": { "description": "Only tickets with this status.", "type": "string", "enum": [ "open", "in_progress", "done" ], "examples": [ "open" ] } }, { "name": "building_id", "in": "query", "required": false, "description": "Only tickets in this building.", "schema": { "description": "Only tickets in this building.", "type": "string", "examples": [ "bld_Linden12" ] } }, { "name": "unit_id", "in": "query", "required": false, "description": "Only tickets in this unit.", "schema": { "description": "Only tickets in this unit.", "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Searches title and description.", "schema": { "description": "Searches title and description.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` value of the previous page.", "schema": { "description": "The `nextCursor` value of the previous page.", "type": "string" } } ], "responses": { "200": { "description": "A page of tickets.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create_ticket", "summary": "Create a ticket", "description": "Creates a ticket in the connected system and optionally assigns it. Without `system` your company's primary system is used.", "tags": [ "Connected systems" ], "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": "Prevents duplicate execution on retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Short title.", "type": "string" }, "description": { "description": "Description of the request.", "type": "string" }, "category": { "description": "Category key from `GET /categories`.", "type": "string" }, "buildingId": { "description": "Building.", "type": "string" }, "unitId": { "description": "Unit.", "type": "string" }, "contactId": { "description": "Reporting person.", "type": "string" }, "priority": { "description": "Urgency.", "type": "string", "enum": [ "low", "normal", "high", "emergency" ], "default": "normal" }, "assignee": { "description": "Assignee in the system.", "type": "string" }, "system": { "description": "Target system if several are connected.", "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": "The created ticket.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/tickets/{ticketId}": { "patch": { "operationId": "update_ticket", "summary": "Update a ticket", "description": "Changes a ticket's status or assignee and optionally adds a comment.", "tags": [ "Connected systems" ], "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 of the ticket.", "schema": { "description": "Id of the ticket.", "type": "string", "examples": [ "casavi:TK-20931" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "New status.", "type": "string", "enum": [ "open", "in_progress", "done" ] }, "assignee": { "description": "New assignee.", "type": "string" }, "comment": { "description": "Comment that appears in the system.", "type": "string" } } }, "example": { "status": "in_progress", "comment": "Heizungsbauer Huber kommt am 15.09. zwischen 8 und 10 Uhr." } } } }, "responses": { "200": { "description": "The updated ticket.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/documents": { "get": { "operationId": "find_documents", "summary": "Search documents", "description": "Finds documents in the connected DMS, for example minutes, statements, house rules or resolutions. The download link is valid for 15 minutes.", "tags": [ "Connected systems" ], "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": "Only documents for this building.", "schema": { "description": "Only documents for this building.", "type": "string", "examples": [ "bld_Linden12" ] } }, { "name": "type", "in": "query", "required": false, "description": "Document type.", "schema": { "description": "Document type.", "type": "string", "enum": [ "meeting_minutes", "annual_statement", "operating_costs", "house_rules", "resolution", "contract", "other" ], "examples": [ "meeting_minutes" ] } }, { "name": "search", "in": "query", "required": false, "description": "Searches title and content.", "schema": { "description": "Searches title and content.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "schema": { "description": "Maximum number of items returned, between 1 and 100. Does not affect `total`.", "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Documents found.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/systems/units/{unitId}": { "get": { "operationId": "einheit-im-system", "summary": "Retrieve a unit with its people", "description": "Returns a unit with its owners, tenants and, if the ERP provides it, the current service charge balance.", "tags": [ "Connected systems" ], "security": [ { "bearerAuth": [ "systems:read" ] } ], "x-scope": "systems:read", "x-beta": true, "parameters": [ { "name": "unitId", "in": "path", "required": true, "description": "Id of the unit.", "schema": { "description": "Id of the unit.", "type": "string", "examples": [ "unit_Linden12_WE04" ] } } ], "responses": { "200": { "description": "The unit.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "SYSTEM_UNAVAILABLE: The connected system did not respond or responded with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "post": { "operationId": "webhook-anlegen", "summary": "Register a webhook", "description": "Registers an HTTPS address for the selected events. You receive the signing secret only in this response, so store it safely.", "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 address of your server.", "type": "string" }, "events": { "description": "Events to deliver.", "type": "array", "items": { "type": "string" } }, "description": { "description": "Internal description.", "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": "The webhook with its secret.", "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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "webhooks-auflisten", "summary": "List webhooks", "description": "Returns your webhooks with the result of their last delivery.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "x-scope": "webhooks:write", "x-beta": true, "responses": { "200": { "description": "The 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: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{webhookId}": { "delete": { "operationId": "webhook-loeschen", "summary": "Remove a webhook", "description": "Removes a webhook. Pending delivery attempts are cancelled.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "x-scope": "webhooks:write", "x-beta": true, "parameters": [ { "name": "webhookId", "in": "path", "required": true, "description": "Id of the webhook.", "schema": { "description": "Id of the webhook.", "type": "string", "examples": [ "wh_3Nf8Pz" ] } } ], "responses": { "204": { "description": "No response body." }, "401": { "description": "INVALID_TOKEN_FORMAT: The key is not in a valid format. TOKEN_EXPIRED: The key has expired or was revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "MISSING_AUTHORIZATION: The `Authorization` header is missing or holds no bearer token. INSUFFICIENT_SCOPE: The key lacks the scope for this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "NOT_FOUND: The requested object does not exist or does not belong to your company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "VALIDATION_ERROR: A parameter is missing or invalid. `errors` names the field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "RATE_LIMITED: Too many requests. Wait for the seconds given in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_ERROR: An unexpected error on our side. Retry the request later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key, starts with 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" }