# Caspar Manufaktur: API-Versionierung und Betrieb

Stand: 1. Oktober 2026. Diese Regeln gelten für die öffentliche Caspar Agent API.

## Versioning and deprecation policy

Die REST-Schnittstelle verwendet die Hauptversion `/wp-json/caspar-agent/v1/`.
Neue optionale Felder und neue Endpunkte können innerhalb von v1 hinzukommen.
Clients sollten unbekannte Antwortfelder ignorieren. Änderungen, die vorhandene
Pflichtfelder, deren Bedeutung oder bestehende Aufrufe inkompatibel verändern,
werden als neue Hauptversion veröffentlicht.

Für planbare Abschaltungen einer unterstützten Hauptversion ist eine
Ankündigung mit mindestens 90 Tagen Vorlauf vorgesehen. Die Ankündigung wird
hier und in der OpenAPI-Dokumentation veröffentlicht und nennt den betroffenen
Endpunkt, das Abschaltdatum und eine Migrationsempfehlung. Für einen tatsächlich
abgekündigten Endpunkt werden die HTTP-Header `Deprecation` und `Sunset`
bereitgestellt. Derzeit ist keine Abschaltung von v1 angekündigt.
Dringende Sicherheitsmaßnahmen können eine kürzere Frist erfordern.

Die Versionsnummer des OpenAPI-Dokuments bezeichnet dessen Dokumentationsstand;
sie ist unabhängig von der installierten Plugin-Version.

## Zugriff und Umfang

Materialinformationen, Empfehlungen und Unternehmensinformationen sind ohne
API-Schlüssel lesbar. Der Material-Endpunkt liefert die vollständige kuratierte
Auswahl der API und keine paginierte Massendatenliste. Sie ist eine Auswahl,
nicht zwingend das gesamte Materialangebot der Website.

Projektübergaben liefern einen Link zu einer menschlich betreuten Anfrage oder
zum Wallcheck. Sie lösen keine Bestellung, Zahlung oder Produktion aus und
übermitteln keine personenbezogenen Projektdaten.

## Idempotency-Key und Wiederholungen

`POST /wp-json/caspar-agent/v1/handoffs` verlangt einen `Idempotency-Key` mit
8–255 Zeichen aus Buchstaben, Ziffern, Punkt, Unterstrich, Doppelpunkt oder
Bindestrich. Derselbe Schlüssel darf ausschließlich für Wiederholungen mit
demselben `next_step` verwendet werden. Für einen anderen Vorgang ist ein neuer
Schlüssel erforderlich.

Die bestehende Implementierung speichert die Antwort in einem WordPress-
Transient mit einer Ablaufzeit von 24 Stunden (86400 Sekunden). Solange dieser
Eintrag vorhanden ist, liefert eine Wiederholung die gespeicherte Antwort mit
HTTP 200 und `Idempotency-Replayed: true`; ein neuer Eintrag liefert HTTP 201.
Caches können einen Transient vor Ablauf entfernen. Die 24 Stunden sind daher
keine garantierte Mindestaufbewahrung oder Zusage einer atomaren Verarbeitung
gleichzeitiger Anfragen. Nach Verlust oder Ablauf des Eintrags kann eine neue
Handoff-ID entstehen. Die Übergabe bleibt ein Link ohne Bestellwirkung.

## Fehler und Retry-Verhalten

Die Caspar-REST-Endpunkte verwenden das WordPress-Fehlerformat mit `code`,
`message` und gegebenenfalls `data.status`. Bei HTTP 400 muss der Client seine
Eingabe korrigieren. Bei vorübergehenden Netzwerk- oder Serverfehlern sollten
Clients eine begrenzte Anzahl Wiederholungen mit zunehmenden Pausen verwenden.
Bei HTTP 429 ist ein vorhandener `Retry-After`-Header zu beachten.

Es werden keine festen Rate-Limits oder verfügbaren Anfragekontingente
zugesichert. Angaben hierzu müssen dem tatsächlich durchgesetzten Serverlimit
entsprechen; statische Beispielwerte sind keine Kontingentanzeige.

## Verfügbarkeit und Support

Die öffentliche API wird als Best-Effort-Service angeboten. Es besteht keine
veröffentlichte Verfügbarkeitsgarantie oder SLA. Clients sollten Lesedaten kurz
zwischenspeichern und bei Nichterreichbarkeit die persönliche Beratung anbieten.

- [Gemeinsame OpenAPI-Spezifikation](https://www.caspar-manufaktur.de/.well-known/openapi.json)
- [Developer Portal](https://www.caspar-manufaktur.de/developers/)
- [Agent-Hinweise](https://www.caspar-manufaktur.de/llms.txt)
- Support: info@caspar-manufaktur.de
- [Persönliche Beratung](https://www.caspar-manufaktur.de/kontakt/)