{ "openapi": "3.1.0", "info": { "title": "mekyn Public API", "version": "1.1.0", "description": "Öffentliche, auth-freie Endpoints der mekyn-Plattform: SEO/AEO/GEO-Audit, Site-Quality-Check (MCS), Core-Web-Vitals-Felddaten, Tarif-Auskunft und Readiness. Authentifizierte Endpoints sind nicht enthalten; Agent-Auth siehe /auth.md.", "contact": { "name": "mekyn", "url": "https://mekyn.com" } }, "servers": [ { "url": "https://mekyn.com" } ], "paths": { "/api/ready": { "get": { "summary": "Readiness-Probe", "description": "Antwortet 200, sobald die API DB-gestützten Traffic bedienen kann, sonst 503.", "operationId": "getReady", "responses": { "200": { "description": "bereit" }, "503": { "description": "nicht bereit" } } } }, "/api/pricing": { "get": { "summary": "Tarife & Add-ons (SSOT)", "operationId": "getPricing", "responses": { "200": { "description": "Tarife free/lite/plus/pro/max + Add-ons" } } } }, "/api/seo-check/audit": { "get": { "summary": "SEO/AEO/GEO-Audit einer Domain", "operationId": "getSeoAudit", "parameters": [ { "name": "d", "in": "query", "required": true, "schema": { "type": "string" }, "description": "zu prüfende Domain, z. B. example.com" }, { "name": "premium", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "tiefere Prüfung" } ], "responses": { "200": { "description": "Score, Achsen (seo/aeo/geo), Findings, Quick-Wins" }, "400": { "description": "fehlender/ungültiger Domain-Parameter" } } } }, "/api/mcs-check": { "get": { "summary": "Site-Quality-Check (MCS, Lighthouse-basiert)", "operationId": "getMcsCheck", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "zu prüfende Domain" } ], "responses": { "200": { "description": "MCS-Score + Lighthouse-Kategorien" }, "400": { "description": "fehlender/ungültiger Domain-Parameter" } } } }, "/api/cwv-tracker": { "get": { "summary": "Core-Web-Vitals-Felddaten (CrUX, CC-BY-4.0)", "operationId": "getCwv", "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "default": "lookup" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CWV-Felddaten" }, "400": { "description": "fehlender Domain-Parameter" } } } }, "/api/agent/bootstrap": { "post": { "summary": "Create or rehydrate a Sales-Agent session", "operationId": "bootstrapSalesAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AgentBootstrapCreateRequest" }, { "$ref": "#/components/schemas/AgentBootstrapRehydrateRequest" } ] } } } }, "responses": { "200": { "description": "Session capability, opener, transcript, and capabilities", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "session_id", "session_token", "locale", "capabilities", "opener", "messages", "handoff", "lead_consent" ], "properties": { "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" }, "locale": { "$ref": "#/components/schemas/AgentLocale" }, "persona": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": false, "required": [ "booking", "lead", "handoff" ], "properties": { "booking": { "type": "boolean" }, "booking_url": { "type": "string" }, "lead": { "type": "boolean" }, "handoff": { "type": "boolean" } } }, "opener": { "type": "object", "additionalProperties": false, "required": [ "text", "suggestions" ], "properties": { "text": { "type": "string" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSuggestion" } } } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/AgentMessage" } }, "handoff": { "$ref": "#/components/schemas/AgentHandoff" }, "lead_consent": { "oneOf": [ { "$ref": "#/components/schemas/AgentLeadConsent" }, { "type": "null" } ] } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "404": { "description": "Feature disabled or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRateLimitError" } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } }, "delete": { "summary": "Erase a capability-authenticated Sales-Agent session", "operationId": "eraseSalesAgentSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "session_id", "session_token" ], "properties": { "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" } } } } } }, "responses": { "204": { "description": "Erased" }, "400": { "description": "Invalid session id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRateLimitError" } } } }, "503": { "description": "Erasure unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } } }, "/api/agent/chat": { "post": { "summary": "Submit one durable Sales-Agent turn", "operationId": "chatWithSalesAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "message", "session_id", "session_token", "turn_id" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" }, "turn_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "url": { "type": "string", "maxLength": 500 }, "locale": { "$ref": "#/components/schemas/AgentLocale" } } } } } }, "responses": { "200": { "description": "Authoritative stored turn response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reply", "session_id", "handoff" ], "properties": { "reply": { "type": "string", "maxLength": 1500 }, "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "actions": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/AgentAction" } }, "suggestions": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/AgentSuggestion" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSource" } }, "handoff": { "$ref": "#/components/schemas/AgentHandoff" }, "usage": { "type": "object", "additionalProperties": false, "required": [ "tokens" ], "properties": { "tokens": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "404": { "description": "Feature disabled or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "409": { "description": "Turn in progress, payload mismatch, or locale mismatch", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AgentError" }, { "$ref": "#/components/schemas/AgentTurnInProgressError" } ] } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRateLimitError" } } } }, "503": { "description": "Agent unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } } }, "/api/agent/event": { "post": { "summary": "Submit a consent-bound lead or a client interaction event", "operationId": "submitSalesAgentEvent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEventRequest" } } } }, "responses": { "200": { "description": "Interaction accepted or safely suppressed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOk" } } } }, "202": { "description": "Consent-bound lead accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLeadAccepted" } } } }, "400": { "description": "Invalid request or consent evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "404": { "description": "Feature disabled or session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "409": { "description": "Consent version mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRateLimitError" } } } }, "503": { "description": "Persistence unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentError" } } } } } } } }, "components": { "schemas": { "AgentLocale": { "type": "string", "enum": [ "de", "en", "fr" ] }, "AgentSessionId": { "type": "string", "pattern": "^ag_[A-Za-z0-9_-]+$", "minLength": 4, "maxLength": 200 }, "AgentSessionToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "AgentHandoff": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "none", "requested", "active", "resolved" ] } } }, "AgentMessage": { "type": "object", "additionalProperties": false, "required": [ "role", "text", "at" ], "properties": { "role": { "type": "string", "enum": [ "visitor", "assistant", "operator" ] }, "text": { "type": "string" }, "at": { "type": "string", "format": "date-time" } } }, "AgentSuggestion": { "type": "object", "additionalProperties": false, "required": [ "label", "prompt" ], "properties": { "label": { "type": "string" }, "prompt": { "type": "string" } } }, "AgentSource": { "type": "object", "additionalProperties": false, "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string", "pattern": "^/" } } }, "AgentLeadConsent": { "type": "object", "additionalProperties": false, "required": [ "version", "locale", "text", "privacy", "digest" ], "properties": { "version": { "const": "2026-07-24.1" }, "locale": { "$ref": "#/components/schemas/AgentLocale" }, "text": { "type": "string", "minLength": 1 }, "privacy": { "type": "object", "additionalProperties": false, "required": [ "label", "url" ], "properties": { "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "pattern": "^/" } } }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "AgentAction": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "href" ], "properties": { "type": { "const": "navigate" }, "href": { "type": "string", "pattern": "^/" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "url" ], "properties": { "type": { "const": "open_booking" }, "url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "phase" ], "properties": { "type": { "const": "capture_lead" }, "phase": { "const": "suggested" } } } ] }, "AgentError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "string" }, "contactFallback": { "type": "boolean" } } }, "AgentRateLimitError": { "type": "object", "additionalProperties": false, "required": [ "error", "code", "retryAfterSeconds" ], "properties": { "error": { "type": "string" }, "code": { "const": "RATE_LIMITED" }, "retryAfterSeconds": { "type": "integer", "minimum": 1 } } }, "AgentTurnInProgressError": { "type": "object", "additionalProperties": false, "required": [ "error", "retry_after_seconds" ], "properties": { "error": { "const": "turn-in-progress" }, "retry_after_seconds": { "type": "integer", "minimum": 1 } } }, "AgentOk": { "type": "object", "additionalProperties": false, "required": [ "ok" ], "properties": { "ok": { "const": true } } }, "AgentLeadAccepted": { "type": "object", "additionalProperties": false, "required": [ "ok", "accepted" ], "properties": { "ok": { "const": true }, "accepted": { "const": true } } }, "AgentBootstrapCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 500 }, "locale": { "$ref": "#/components/schemas/AgentLocale" } } }, "AgentBootstrapRehydrateRequest": { "type": "object", "additionalProperties": false, "required": [ "session_id", "session_token" ], "properties": { "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" }, "url": { "type": "string", "maxLength": 500 }, "locale": { "$ref": "#/components/schemas/AgentLocale" } } }, "AgentLeadSubmission": { "type": "object", "additionalProperties": false, "required": [ "email", "consent", "consent_version", "consent_digest" ], "properties": { "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 254 }, "name": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 1000 }, "consent": { "const": true }, "consent_version": { "const": "2026-07-24.1" }, "consent_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } }, "AgentMetricEventRequest": { "type": "object", "additionalProperties": false, "required": [ "session_id", "session_token", "type" ], "properties": { "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" }, "type": { "type": "string", "enum": [ "assistant_surfaced", "assistant_opened", "assistant_dismissed", "assistant_closed", "suggestion_clicked", "action_clicked", "booking_opened", "handoff_ack" ] } } }, "AgentLeadEventRequest": { "type": "object", "additionalProperties": false, "required": [ "session_id", "session_token", "type", "payload" ], "properties": { "session_id": { "$ref": "#/components/schemas/AgentSessionId" }, "session_token": { "$ref": "#/components/schemas/AgentSessionToken" }, "type": { "const": "lead_submitted" }, "payload": { "$ref": "#/components/schemas/AgentLeadSubmission" } } }, "AgentEventRequest": { "oneOf": [ { "$ref": "#/components/schemas/AgentMetricEventRequest" }, { "$ref": "#/components/schemas/AgentLeadEventRequest" } ] } } }, "x-sales-agent-interface": { "version": "sales-agent-public.v2", "sha256": "788d81e1ec5c7d715ffebf6b4d2b93e56a9be500f44318e1dd49bd03ad59d659" } }