{ "openapi": "3.0.3", "info": { "title": "Agent-to-Agent Commerce API", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://www.agent-to-agent-commerce.de/impressum" }, "description": "Öffentliche Schnittstelle der deutschsprachigen Referenz- und Beratungsseite zu Agentic Commerce. Bietet deterministische Begriffsauskunft (A2A/JSON-RPC), einen Seitenindex und Lead-Erfassung.", "x-versioning": "URL-Pfad-Versionierung unter /v1 (Alias auf /api).", "x-deprecation-policy": "Alte Versionen bleiben 12 Monate unter /v{N} erreichbar." }, "servers": [ { "url": "https://www.agent-to-agent-commerce.de" } ], "security": [], "externalDocs": { "description": "Agent-to-Agent Commerce developer documentation", "url": "https://www.agent-to-agent-commerce.de/developers" }, "x-versioning": "Canonical URL path versioning under /v1; legacy /api aliases remain available during the transition.", "x-deprecation-policy": "Deprecated operations carry Deprecation and Sunset headers and remain available for at least 12 months.", "x-deprecation-policy-url": "https://www.agent-to-agent-commerce.de/api-policy.md", "x-sandbox": { "url": "https://www.agent-to-agent-commerce.de/sandbox", "description": "Anonymous read-only sandbox; no leads, payments, orders or production records can be created.", "endpoints": [ "/sandbox/v1/a2a", "/sandbox/v1/batch", "/sandbox/ask", "/sandbox/mcp" ] }, "paths": { "/v1/a2a": { "get": { "summary": "A2A-Endpunkt und Fähigkeiten beschreiben", "operationId": "getA2ACapabilities", "description": "Liefert Protokollversion, unterstützte Methode, Agent Card und die verfügbaren deterministischen Skills.", "responses": { "200": { "description": "A2A-Endpunktbeschreibung", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ACapabilities" } } } }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "A2A-Leitfaden-Auskunft (JSON-RPC)", "operationId": "a2aMessageSend", "description": "Deterministische Begriffsauskunft aus der Glossar-/Readiness-/Index-Registry. Methode message/send (A2A v1.0). Kein Modellaufruf.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2ARequest" } } } }, "responses": { "200": { "description": "A2A-Antwort (message oder JSON-RPC error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/A2AResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/lead": { "post": { "summary": "Lead-Anfrage / Kontakt", "operationId": "createLead", "description": "Übermittelt eine freiwillige Kontaktanfrage aus dem Readiness-Check. Personenbezogene Daten nur nach Einwilligung des Nutzers senden.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" } } } }, "responses": { "200": { "description": "Lead angenommen und zugestellt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/mcp": { "get": { "summary": "MCP-Server beschreiben", "operationId": "getMcpServer", "description": "Liefert den zustandslosen MCP-Streamable-HTTP-Endpunkt, die Protokollversion und eine kompakte Tool-Liste.", "responses": { "200": { "description": "MCP-Serverbeschreibung", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPServerInfo" } } } }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "MCP JSON-RPC ausführen", "operationId": "callMcp", "description": "Implementiert MCP Streamable HTTP 2025-06-18 für initialize, ping, tools/list und tools/call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPRequest" } } } }, "responses": { "200": { "description": "MCP JSON-RPC-Ergebnis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MCPResponse" } } } }, "202": { "description": "Benachrichtigung wurde ohne Antwortkörper akzeptiert" }, "400": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/v1/batch": { "post": { "summary": "Mehrere Wissensanfragen bündeln", "operationId": "batchLookup", "description": "Verarbeitet 1 bis 20 unabhängige, ausschließlich lesende Suchanfragen in einem HTTP-Aufruf.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Geordnete Ergebnisse je Anfrage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } }, "/ask": { "get": { "summary": "NLWeb-Inhalte durchsuchen", "operationId": "askAgenticCommerce", "description": "Durchsucht die gepflegte Seitenregistry per NLWeb-kompatibler natürlicher Anfrage und liefert kanonische Treffer.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Natürlichsprachige Suchanfrage", "schema": { "type": "string", "minLength": 2 } }, { "name": "streaming", "in": "query", "required": false, "description": "true liefert Server-Sent Events", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "NLWeb-Treffer als JSON oder SSE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } }, "post": { "summary": "NLWeb-Anfrage ausführen", "operationId": "postAskAgenticCommerce", "description": "Akzeptiert eine NLWeb-Anfrage als JSON; prefer.streaming aktiviert eine SSE-Ereignisfolge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskRequest" } } } }, "responses": { "200": { "description": "NLWeb-Treffer als JSON oder SSE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } } } } }, "components": { "responses": { "Error": { "description": "Typed REST or protocol error response", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } }, "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcErrorEnvelope" } } } } }, "schemas": { "A2ACapabilities": { "type": "object", "required": [ "service", "protocolVersion", "binding", "methods", "agentCard", "skills" ], "properties": { "service": { "type": "string" }, "protocolVersion": { "type": "string" }, "binding": { "type": "string" }, "methods": { "type": "array", "items": { "type": "string" } }, "agentCard": { "type": "string", "format": "uri" }, "hint": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } } } }, "MCPServerInfo": { "type": "object", "required": [ "name", "protocolVersion", "transport", "endpoint", "documentation", "tools" ], "properties": { "name": { "type": "string" }, "protocolVersion": { "type": "string" }, "transport": { "type": "string", "enum": [ "streamable-http" ] }, "endpoint": { "type": "string", "format": "uri" }, "documentation": { "type": "string", "format": "uri" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/MCPToolSummary" } } } }, "MCPToolSummary": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "BatchRequest": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1 } } } }, "BatchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BatchResult" } } } }, "BatchResult": { "type": "object", "required": [ "query", "matches" ], "properties": { "query": { "type": "string" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/AskResult" } } } }, "AskRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 2 }, "prefer": { "type": "object", "properties": { "streaming": { "type": "boolean", "default": false } } } } }, "AskResponse": { "type": "object", "required": [ "_meta", "query", "results" ], "properties": { "_meta": { "type": "object", "required": [ "response_type", "version" ], "properties": { "response_type": { "type": "string" }, "version": { "type": "string" }, "source": { "type": "string" } } }, "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AskResult" } } } }, "AskResult": { "type": "object", "required": [ "score", "name", "description", "url", "type" ], "properties": { "score": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string" } } }, "Problem": { "type": "object", "required": [ "title", "status", "code", "message", "resolution" ], "properties": { "type": { "type": "string" }, "title": { "type": "string", "description": "Menschlich lesbare Fehlerbeschreibung" }, "status": { "type": "integer" }, "code": { "type": "string", "description": "Maschinenlesbarer Fehlercode" }, "detail": { "type": "string" }, "message": { "type": "string", "description": "Human-readable error message" }, "instance": { "type": "string" }, "resolution": { "type": "string", "description": "Konkreter nächster Schritt zur Behebung" } } }, "JsonRpcErrorEnvelope": { "type": "object", "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "additionalProperties": true } } } } }, "A2ARequest": { "type": "object", "required": [ "jsonrpc", "method", "params" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string" }, "params": { "type": "object" }, "id": { "type": "integer" } } }, "A2AResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": "integer", "nullable": true }, "result": { "type": "object" }, "error": { "$ref": "#/components/schemas/JsonRpcErrorEnvelope/properties/error" } } }, "MCPRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "method": { "type": "string", "enum": [ "initialize", "ping", "tools/list", "tools/call" ] }, "params": { "type": "object", "additionalProperties": true } } }, "MCPResponse": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }, "result": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/JsonRpcErrorEnvelope/properties/error" } } }, "Lead": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "score": { "type": "integer" }, "tier": { "type": "string" }, "source": { "type": "string" }, "page": { "type": "string" } } }, "LeadResult": { "type": "object", "required": [ "ok", "delivered" ], "properties": { "ok": { "type": "boolean" }, "delivered": { "type": "array", "items": { "type": "string", "enum": [ "slack", "email" ] } } } } } } }