API-Referenz¶

Für interaktive API-Docs mit laufendem Backend:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Print & Export (REQ-032)¶

Alle Print-Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{slug}/print/ und erfordern ein gültiges JWT-Token. Die Zugriffsrechte entsprechen den Berechtigungen der zugrundeliegenden Daten (REQ-024 RBAC) — wer einen Nährstoffplan lesen darf, darf ihn auch drucken.

Gemeinsame Query-Parameter (alle Endpunkte):

Nährstoffplan-PDF¶

Exportiert einen vollständigen Nährstoffplan als PDF inklusive Phasen-Tabelle, Mischanleitungen, Wasser-Konfiguration und CalMag/Flushing-Hinweisen.

GET /api/v1/t/{slug}/print/nutrient-plan/{plan_key}

Pfad-Parameter:

Response: application/pdf mit Content-Disposition: attachment; filename="naehrstoffplan-{plan_key}.pdf"

Beispiel:

curl -X GET \
  "https://api.example.com/api/v1/t/mein-garten/print/nutrient-plan/nutrient_plans/42?locale=de" \
  -H "Authorization: Bearer <token>" \
  --output naehrstoffplan.pdf

Pflege-Checkliste-PDF¶

Exportiert alle fälligen Pflegeaufgaben für ein bestimmtes Datum als Checkliste mit Checkboxen, gruppiert nach Dringlichkeit (überfällig, heute fällig, demnächst).

GET /api/v1/t/{slug}/print/care-checklist

Query-Parameter (zusätzlich zu locale und format):

Response: application/pdf mit Content-Disposition: attachment; filename="pflege-checkliste-{date}.pdf"

Beispiel:

curl -X GET \
  "https://api.example.com/api/v1/t/mein-garten/print/care-checklist?date=2026-04-15&locale=de" \
  -H "Authorization: Bearer <token>" \
  --output pflege-checkliste.pdf

Pflanzen-Infokarten / Etiketten-PDF¶

Druckt kompakte Infokarten mit QR-Code für eine oder mehrere Pflanzinstanzen. Der QR-Code enthält die Deep-Link-URL zur jeweiligen Pflanze in der App.

GET /api/v1/t/{slug}/print/plant-labels

Query-Parameter (zusätzlich zu locale):

Mögliche Werte für fields:

name, scientific_name, family, planted_date, current_phase, location, cultivar, note

Der QR-Code ist immer enthalten und kann nicht über fields abgewählt werden.

Response: application/pdf mit Content-Disposition: attachment; filename="pflanzen-etiketten.pdf"

Beispiel — 8 Karten pro A4-Seite mit Pflanzenname, wissenschaftlichem Namen und Pflanzdatum:

curl -X GET \
  "https://api.example.com/api/v1/t/mein-garten/print/plant-labels\
?plant_keys=plant_instances/101,plant_instances/102,plant_instances/103\
&fields=name,scientific_name,planted_date,location\
&layout=grid_2x4\
&qr_size_mm=25\
&locale=de" \
  -H "Authorization: Bearer <token>" \
  --output etiketten.pdf

Fehlercodes:

Verfügbare Templates auflisten¶

Gibt eine Liste aller registrierten Print-Templates zurück.

GET /api/v1/print/templates

Dieser Endpunkt ist nicht mandantenspezifisch und erfordert lediglich eine gültige Authentifizierung.

Response-Beispiel:

[
  {
    "type": "nutrient_plan",
    "label_de": "Nährstoffplan",
    "label_en": "Nutrient Plan",
    "formats": ["pdf"],
    "locales": ["de", "en"]
  },
  {
    "type": "care_checklist",
    "label_de": "Pflege-Checkliste",
    "label_en": "Care Checklist",
    "formats": ["pdf"],
    "locales": ["de", "en"]
  },
  {
    "type": "plant_label",
    "label_de": "Pflanzen-Infokarte",
    "label_en": "Plant Info Card",
    "formats": ["pdf"],
    "locales": ["de", "en"]
  }
]

Browser Push / PWA-Benachrichtigungen¶

Alle drei Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/notifications/pwa/ und erfordern ein gültiges JWT-Token.

VAPID-Public-Key abrufen¶

Gibt den VAPID-Public-Key der Instanz zurück. Der Browser benötigt diesen Schlüssel, um eine Push-Subscription zu erstellen.

GET /api/v1/t/{tenant_slug}/notifications/pwa/vapid-public-key

Response (200):

{
  "vapid_public_key": "BNm..."
}

Ist kein VAPID-Schlüsselpaar konfiguriert, antwortet der Endpunkt mit 503 Service Unavailable.

Push-Subscription registrieren¶

Registriert das aktuelle Gerät für Browser-Push-Benachrichtigungen. Die Subscription-Daten werden vom Browser nach dem Aufruf von PushManager.subscribe() bereitgestellt.

POST /api/v1/t/{tenant_slug}/notifications/pwa/subscribe

Request-Body:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "...",
    "auth": "..."
  }
}

Response: 201 Created bei Erfolg, 409 Conflict wenn die Subscription für dieses Gerät bereits registriert ist.

Push-Subscription deregistrieren¶

Entfernt die Subscription des aktuellen Geräts. Danach werden keine Browser-Push-Benachrichtigungen mehr an dieses Gerät gesendet.

POST /api/v1/t/{tenant_slug}/notifications/pwa/unsubscribe

Request-Body:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/..."
}

Response: 204 No Content bei Erfolg, 404 Not Found wenn die Subscription nicht gefunden wurde.

Siehe auch¶

• Druckansichten & Export — Benutzerhandbuch
• Dünge-Logik
• Pflegeerinnerungen
• Umgebungsvariablen — Browser Push (VAPID)

Standort-Wettervorhersage & Frost-Frühwarnung ¶

Beide Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/ und erfordern ein gültiges JWT-Token. Es gibt keine gesonderte Rollen-Einschränkung — jedes aktive Mandanten-Mitglied (auch die Rolle Beobachter) darf lesen. Beide Endpunkte sind graceful: Fehlt eine Wetterquelle, fehlen GPS-Koordinaten am Standort, oder ist die Wettervorhersage-Funktion betreiberseitig deaktiviert (WEATHER_ENABLED=false), liefern sie leere/null-Vorhersagefelder statt eines Fehlers.

Wetter-Tagesvorhersage eines Standorts abrufen¶

Liefert die im Vorhersage-Zeitraum liegenden Tagesvorhersagen eines Standorts (aus der Wetterquellen-Infrastruktur) plus die zusammengefasste proaktive Frost-Frühwarnung. Speist das Dashboard-Widget „Wettervorhersage".

GET /api/v1/t/{tenant_slug}/sites/{site_key}/weather-forecast

Response (200): SiteWeatherForecastResponse

{
  "site_key": "sites/42",
  "forecasts": [
    {
      "forecast_date": "2026-07-07",
      "temp_min_c": -1.5,
      "temp_max_c": 6.0,
      "precipitation_mm": 0.0,
      "wind_speed_kmh": 10.0,
      "humidity_percent": 80.0,
      "weather_code": "clear",
      "source": "open-meteo",
      "data_kind": "forecast"
    }
  ],
  "forecast_frost_warning": true,
  "forecast_min_temperature": -1.5,
  "forecast_expected_date": "2026-07-07",
  "forecast_source": "open-meteo"
}

Zusätzliche Felder in der Frost-Warnung eines Standorts (Location)¶

Die bestehende reaktive Frost-Warnung liefert seit dieser Erweiterung zusätzlich die proaktive Vorhersage für die Site, zu der dieser Standort gehört. Das reaktive Feld frost_warning bleibt unverändert, damit der Home-Assistant-Koordinator kompatibel bleibt.

GET /api/v1/t/{tenant_slug}/locations/{key}/frost-warning

Response (200): FrostWarningResponse — zusätzlich zu den bestehenden Feldern (location_key, frost_warning, temperature_celsius, threshold_celsius, source, entity_id):

Siehe auch¶

• Dashboard: Wettervorhersage und Frost-Frühwarnung — Benutzerhandbuch
• Benachrichtigungen: Frost-Frühwarnung — Benutzerhandbuch
• Wetterquellen je Standort — Benutzerhandbuch
• Umgebungsvariablen — Wettervorhersage & Frost-Frühwarnung

Standort-Klimanormalen (NASA POWER) ¶

Liefert die langjährigen monatlichen Klima-Normalwerte eines Standorts für den Abschnitt „Klima am Standort" der Standort-Detailseite. Der Endpunkt liegt unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/ und erfordert ein gültiges JWT-Token; jedes aktive Mandanten-Mitglied (auch die Rolle Beobachter) darf lesen. Standort-Besitz wird serverseitig geprüft (404 unbekannt / 403 fremd). Der Endpunkt ist graceful: Liegen für einen berechtigten Standort noch keine Klimanormalen vor (Hintergrund-Abholung noch nicht gelaufen), liefert er eine leere normals-Liste statt eines Fehlers.

Klima-Normalwerte eines Standorts abrufen¶

GET /api/v1/t/{tenant_slug}/sites/{site_key}/climate-normals

Response (200): SiteClimateResponse

{
  "site_key": "sites/42",
  "normals": [
    {
      "source": "nasa-power",
      "attribution": "Klima- und Strahlungsdaten: NASA POWER (power.larc.nasa.gov)",
      "period_start_year": 1991,
      "period_end_year": 2020,
      "monthly_temp_min_c": [-3.1, -2.6, 0.4, 3.8, 8.2, 11.4, 13.1, 12.8, 9.6, 5.7, 1.3, -1.9],
      "monthly_temp_max_c": [2.4, 3.9, 8.1, 13.2, 18.0, 21.3, 23.6, 23.2, 18.9, 13.1, 7.0, 3.2],
      "monthly_temp_avg_c": [-0.4, 0.6, 4.2, 8.5, 13.1, 16.4, 18.4, 18.0, 14.2, 9.4, 4.1, 0.6],
      "monthly_precip_mm": [42.0, 33.0, 40.0, 37.0, 55.0, 68.0, 62.0, 58.0, 45.0, 39.0, 48.0, 47.0],
      "monthly_solar_mj_m2": [4.1, 7.2, 11.5, 16.3, 19.8, 21.0, 20.4, 17.6, 12.5, 7.4, 4.0, 3.1],
      "coldest_month_min_c": -3.1,
      "annual_temp_avg_c": 8.9,
      "annual_precip_mm": 574.0,
      "fetched_at": "2026-07-01T03:12:00Z"
    }
  ]
}

Siehe auch¶

• Klima am Standort — Benutzerhandbuch
• Umgebungsvariablen — Klimanormalen (NASA POWER)

Winterhärtezonen (USDA) ¶

Automatische Ableitung der USDA-Winterhärtezone eines Standorts aus seinen Klimanormalen (kälteste Monats-Tiefsttemperatur), nach dem lizenzfreien USDA-Zonenschema (26 Halbzonen 1a–13b, keine proprietären USDA-/PHZM-/PRISM-Kartendaten). Ersetzt für den Ampel-Vergleich das freie Textfeld Site.climate_zone, das aus Kompatibilitätsgründen weiterhin mitgepflegt und automatisch synchron gehalten wird. Speist die Winterhärte-Ampel mehrjähriger Pflanzen.

Der globale Katalog ist Referenzdaten (wie botanische Familien) und liegt ohne Mandanten-Präfix unter /api/v1/hardiness-zones; die Ableitung und der Lesezugriff pro Standort sind mandantenscoped unter /api/v1/t/{tenant_slug}/sites/{site_key}/. Alle Endpunkte erfordern ein gültiges JWT-Token.

Globalen Zonen-Katalog auflisten¶

GET /api/v1/hardiness-zones

Response (200): Liste von HardinessZoneResponse, sortiert von der kältesten zur wärmsten Zone.

[
  {
    "zone": "7a",
    "zone_number": 7,
    "subzone": "a",
    "temp_min_c": -17.7,
    "temp_max_c": -15.0,
    "temp_min_f": 0.0,
    "temp_max_f": 5.0,
    "description_de": "Mild-gemäßigtes Klima weiter Tieflandregionen. Günstige Zone für die Freilandkultur der meisten winterharten Stauden und Gehölze.",
    "representative_regions_de": ["Norddeutsches Tiefland", "Wiener Becken", "Genferseeregion"],
    "typical_last_frost_md": "05-08",
    "typical_first_frost_md": "10-20"
  }
]

Nur die DACH-relevanten Zonen 5a–9a tragen kuratierte deutsche Beschreibungen und Regionsbeispiele; alle übrigen Zonen des weltweiten Spektrums 1a–13b besitzen eine generische Beschreibung ohne representative_regions_de.

Einzelne Zone abrufen¶

GET /api/v1/hardiness-zones/{zone}

Pfad-Parameter: zone — Zonen-Label im Format <Zahl><a|b>, z. B. 7a.

Fehlercodes: 404, wenn zone kein gültiges Label im Katalog ist.

Winterhärtezone eines Standorts lesen¶

GET /api/v1/t/{tenant_slug}/sites/{site_key}/hardiness

Jedes aktive Mandanten-Mitglied (auch die Rolle Beobachter) darf lesen. Standort-Besitz wird serverseitig geprüft (404 bei unbekanntem/fremdem Standort).

Response (200): SiteHardinessResponse

{
  "site_key": "sites/42",
  "hardiness_zone": "7a",
  "hardiness_zone_source": "derived_gps",
  "hardiness_zone_resolved_at": "2026-07-01T05:00:00Z",
  "mean_annual_minimum_c": -17.2,
  "last_frost_date_avg": "2026-05-08",
  "first_frost_date_avg": "2026-10-20",
  "zone": { "zone": "7a", "...": "vollständiger Katalog-Eintrag wie oben" }
}

hardiness_zone_source ∈ manual (nie automatisch überschrieben), derived_gps (aus Klimanormalen abgeleitet). Die Werte derived_postal und frostline_us sind für künftige, bislang nicht umgesetzte Ableitungswege reserviert.

Winterhärtezone eines Standorts (neu) ableiten¶

POST /api/v1/t/{tenant_slug}/sites/{site_key}/resolve-hardiness-zone

Query-Parameter:

Ohne force=true bleibt eine manuell gesetzte Zone (hardiness_zone_source: manual) unangetastet — der Endpunkt liefert dann unverändert die vorhandene Zone zurück. Befüllt zusätzlich, sofern noch nicht gesetzt, die Frost-Richtwerte des Standorts (last_frost_date_avg, first_frost_date_avg) aus dem Katalog-Eintrag der ermittelten Zone. Ein regulärer PUT-Aufruf auf den Standort mit gesetztem hardiness_zone-Feld im Request-Body markiert die Zone stattdessen direkt als manual.

Response (200): SiteHardinessResponse (siehe oben).

Fehlercodes:

Siehe auch¶

• Klimazonen & Winterhärte — Benutzerhandbuch
• Überwinterung — Benutzerhandbuch
• Standort-Klimanormalen (NASA POWER)
• Umgebungsvariablen — Winterhärtezonen

Pflanzinstanzen: Entfernen mit Abschlussart & Überlebens-Statistik¶

Alle Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/plant-instances/ und erfordern ein gültiges JWT-Token.

Pflanze entfernen (mit optionaler Abschlussklassifizierung)¶

Entfernt eine Pflanzinstanz. Der Request-Body ist optional und abwärtskompatibel: ein leerer Body (bzw. gar kein Body) entspricht dem bisherigen einfachen Entfernen ohne Klassifizierung.

POST /api/v1/t/{tenant_slug}/plant-instances/{key}/remove

Request-Body (optional):

{
  "termination_type": "died",
  "termination_cause": "pest"
}

Verhalten:

• Ohne Body oder mit termination_type: null: reines Entfernen, wie vor der Einführung dieser Felder — removed_on wird gesetzt, keine weitere Klassifizierung.
• Mit termination_type: "died": Die aktuelle Wachstumsphase wird über die Phasenübergangs-Engine eingefroren (der offene Phasenhistorie-Eintrag wird geschlossen, ohne eine Seneszenz-Transition auszulösen), und termination_cause wird für die Verlustursachen-Auswertung übernommen.
• Bei jedem Wert von termination_type: Offene Aufgaben und Pflegeerinnerungen der Pflanze werden aus der Warteschlange entfernt; abgeschlossene/übersprungene Aufgaben bleiben als Historie erhalten.

Response (200): PlantResponse — enthält jetzt zusätzlich die Felder termination_type und termination_cause (beide null, wenn nicht klassifiziert).

Fehlercodes:

Beispiel — Verlust durch Schädlingsbefall:

curl -X POST \
  "https://api.example.com/api/v1/t/mein-garten/plant-instances/plant_instances/101/remove" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"termination_type": "died", "termination_cause": "pest"}'

Überlebens-Statistik abrufen¶

Liefert eine mandantenweite Auswertung aller Pflanzinstanzen: Überlebensrate, Aufschlüsselung nach Abschlussart, nach Wachstumsphase (nur ungeplante Verluste) und nach Verlustursache.

GET /api/v1/t/{tenant_slug}/plant-instances/survival-stats

Response (200):

{
  "total": 42,
  "terminated": 18,
  "active": 24,
  "died": 3,
  "survived": 39,
  "survival_rate": 0.9286,
  "by_termination_type": [
    { "termination_type": "harvested", "count": 12 },
    { "termination_type": "died", "count": 3 },
    { "termination_type": "cancelled", "count": 2 },
    { "termination_type": "senesced", "count": 1 }
  ],
  "by_termination_cause": [
    { "termination_cause": "pest", "count": 2 },
    { "termination_cause": "frost", "count": 1 }
  ],
  "loss_by_phase": [
    { "phase_name": "seedling", "count": 2 },
    { "phase_name": "vegetative", "count": 1 }
  ]
}

survived zählt jede Pflanze, die kein ungeplanter Verlust war — geerntete, natürlich abgestorbene, abgebrochene und noch aktive Pflanzen zählen alle als überlebt; nur termination_type: "died" zählt als Verlust. loss_by_phase ist nach dem aufgelösten Phasen-Namen aggregiert (nicht nach Phasen-Key), damit dieselbe kanonische Phase über mehrere Arten hinweg zusammengefasst wird, und absteigend nach Anzahl sortiert.

Siehe auch¶

• Wachstumsphasen — Benutzerhandbuch: Eine Pflanze entfernen
• Wachstumsphasen — Benutzerhandbuch: Überlebensrate und Verlustursachen auswerten
• Fehlerbehandlung

Pflanzinstanzen: Kindel-Abstammung (mother_key)¶

Wenn eine monokarpische Mutterpflanze automatisch in ihre letzte Blühphase wechselt, erzeugt Kamerplanter automatisch eine neue Pflanzinstanz (das Kindel) und verknüpft sie mit der Mutterpflanze.

Zusätzliches Feld in der Pflanzinstanz-Antwort¶

GET /api/v1/t/{tenant_slug}/plant-instances/{key}

Die PlantResponse enthält seit dieser Erweiterung zusätzlich:

Die maßgebliche Abstammungsbeziehung ist zusätzlich als Graph-Kante descended_from (Kindel → Mutter) hinterlegt; mother_key spiegelt sie für einen günstigen Zugriff aus dem Frontend, ohne dass dafür eine Graph-Traversal-Abfrage nötig ist.

Auslöser und Verhalten¶

• Der automatische Kindel-Spawn wird ausgelöst, sobald eine als monokarpisch konfigurierte Pflanzenart (flowering_strategy: "monocarpic") automatisch in eine ihrer terminalen reproduktiven Phasen (Blüte, Fruchtentwicklung oder Reife) übergeht.
• Genau eine neue Pflanzinstanz wird angelegt; ein erneutes Auswerten desselben Übergangs erzeugt kein zweites Kindel (idempotent — geprüft über das Vorhandensein einer eingehenden descended_from-Kante der Mutter).
• Das Kindel übernimmt tenant_key, species_key, cultivar_key und den Standort der Mutter, aber keinen Platz (slot_key: null) — die Mutterpflanze behält ihren Platz, während sie seneszent auswelkt. Als planted_on wird das Datum des Übergangs übernommen.
• Zusätzlich zur Kante wird ein PropagationEvent mit method: "clone" persistiert (Mutter → Kindel).

Siehe auch¶

• Wachstumsphasen — Benutzerhandbuch: Monokarpische Pflanzen
• Vermehrungsmanagement — Benutzerhandbuch
• Datenbankschema — Pflanzinstanz-Graph

Lebenszyklus-Konfiguration: Abgeleitetes Feld grown_as_annual¶

Botanisch mehrjährige Arten, die in der Praxis wie einjährige Pflanzen kultiviert werden (klassisches Beispiel: die Tomate), erhalten in der Lebenszyklus-Antwort ein abgeleitetes, rein lesendes Flag.

Zusätzliches Feld in der Lebenszyklus-Antwort¶

GET /api/v1/species/{species_key}/lifecycle

Die LifecycleResponse enthält zusätzlich:

Siehe auch¶

• Wachstumsphasen — Benutzerhandbuch: Botanischer Lebenszyklus vs. Anbau-Zyklustyp

Saison- & Überwinterungs-Automatik¶

Diese Endpunkte lesen den automatisch berechneten Saison-Zustand eines Standorts und das automatisch materialisierte Überwinterungsprofil einer Pflanze. Beides entsteht ohne Nutzerinteraktion, sobald eine Pflanze an einer frostexponierten Location zugeordnet wird — standardmäßig einer Location auf einem Freiland-, Gewächshaus- oder Balkon-Standort (OVERWINTERING_SITE_TYPES), oder einer Location mit einer manuellen Frostexpositions-Übersteuerung auf einem andersartigen Standort (siehe Frostexposition einer Location festlegen) — beim Anlegen der Pflanze, bei einem Standortwechsel, sowie zusätzlich als Sicherheitsnetz aus der täglichen Saison-Auswertung — siehe Saison-Automatik und Überwinterung im Benutzerhandbuch.

Alle Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/ und erfordern ein gültiges JWT-Token.

Saison-Zustand eines Standorts lesen¶

GET /api/v1/t/{tenant_slug}/sites/{site_key}/season-state

Response (200):

{
  "site_key": "sites/12",
  "season_state_id": "season-4f2a9c1b3d0e",
  "phase": "pre_winter",
  "trigger_tier": "live",
  "trigger_reason_i18n_key": "pages.season.trigger.frostForecast",
  "season_year": 2026,
  "entered_phase_at": "2026-10-18T06:30:00Z",
  "last_min_temp_c": 3.5,
  "forecast_first_frost_date": "2026-10-24",
  "estimated_first_frost_md": "10-20",
  "estimated_last_frost_md": "04-15",
  "evaluated_at": "2026-10-19T06:30:00Z"
}

phase ∈ growing, pre_winter, winter_dormancy, pre_spring. trigger_tier ∈ live, climatological, calendar — welche Kaskadenstufe (siehe Saison-Automatik) den Zustand aktuell bestimmt.

Existiert für den Standort noch kein Saison-Zustand, wertet der Endpunkt ihn lazy aus und persistiert das Ergebnis, statt 404 zurückzugeben.

Fehlercodes:

Saison-Übersicht über alle Standorte¶

GET /api/v1/t/{tenant_slug}/season/overview

Liefert {"states": [ ... ]} mit einem SeasonStateResponse-Objekt (siehe oben) je frostexponiertem Standort des Mandanten — das sind Standorte vom Typ Freiland, Gewächshaus oder Balkon sowie andersartige Standorte mit mindestens einer manuell als frostexponiert markierten Location. Speist das Dashboard-Widget „Winterschutz" (siehe Dashboard personalisieren).

Überwinterungsprofil einer Pflanze lesen¶

GET /api/v1/t/{tenant_slug}/plants/{plant_key}/overwintering

Response (200): das OverwinteringProfile-Objekt inklusive auto_generated, user_overridden, derived_path (A = in-situ, B = verlagert) und materialized_at.

Fehlercodes: 404 wenn die Pflanze kein (materialisiertes) Profil hat — z. B. weil sie winterhart ist, an keinem frostexponierten Standort steht, oder noch kein Übergang in „Winter kündigt sich an" stattgefunden hat.

Überwinterungsstatus einer Pflanze lesen¶

GET /api/v1/t/{tenant_slug}/plants/{plant_key}/overwintering/status

Additiver, rein lesender Begleit-Endpunkt zu GET .../overwintering: liefert immer 200, auch ganz ohne Profil — praktisch für die Pflanzen-Detailseite, um zwischen „winterhart", „Schutz nötig, Plan folgt" und „Standort nicht frostexponiert" zu unterscheiden, ohne den 404-Fall des Profil-Endpunkts dafür zu missbrauchen.

Response (200): PlantOverwinteringStatus-Objekt:

{
  "has_profile": false,
  "hardiness_light": "yellow",
  "will_materialize": true,
  "site_overwinterable": true
}

Fehlercodes: keine — der Endpunkt antwortet immer mit 200, auch für eine fremde oder unauflösbare Pflanze (Schutz vor einem Cross-Tenant-Existence-Oracle über den 404-Unterschied).

Überwinterungsprofil übersteuern¶

PATCH /api/v1/t/{tenant_slug}/plants/{plant_key}/overwintering

Setzt einzelne Felder des Profils und markiert es als user_overridden: true. Danach ergänzt die Automatik nur noch fehlende Felder, überschreibt aber keine gesetzten Werte mehr.

Fehlercodes:

Überwinterungsprofil auf Automatik zurücksetzen¶

POST /api/v1/t/{tenant_slug}/plants/{plant_key}/overwintering/reset

Setzt user_overridden auf false zurück und materialisiert das Profil erneut vollständig aus dem Art-Steckbrief und der Winterhärte-Ampel des Standorts.

Fehlercodes: 404 wenn Pflanze oder Profil nicht gefunden werden bzw. nicht zum Mandanten gehören.

Siehe auch¶

• Saison-Automatik — Benutzerhandbuch
• Überwinterung — Benutzerhandbuch
• Umgebungsvariablen — Saison- & Überwinterungs-Automatik
• Fehlerbehandlung

Pflanzenerkennung: Referenzbild-Beitrag (Self-Hosted-Erkennung)¶

Beim Anlegen einer Pflanze aus einer Foto-Identifikation heraus kann ein Nutzer das Identifikationsfoto optional als Trainingsreferenz für die selbst-gehostete DINOv2-Erkennung beitragen (siehe Foto der neuen Pflanze zuordnen — Benutzerhandbuch).

POST /api/v1/t/{tenant_slug}/identification/reference

Erfordert ein gültiges JWT-Token und mindestens die Mandanten-Rolle grower. Nur verfügbar, wenn die selbst-gehostete DINOv2-Erkennung aktiv ist (INFERENCE_SERVICE_ENABLED=true) — der externe Pl@ntNet-Pfad besitzt keinen lokalen Referenz-Index.

Request-Body: multipart/form-data

Response (202 Accepted): ReferenceContributionResponse

{
  "accepted": true,
  "pending_review": true,
  "species_key": "species/123",
  "dim": 768
}

Fehlercodes:

Siehe auch¶

• Pflanze per Foto identifizieren — Benutzerhandbuch: Foto der neuen Pflanze zuordnen
• Referenzbilder kuratieren — Benutzerhandbuch
• Umgebungsvariablen — Foto-Identifikation
• Fehlerbehandlung

KI-Assistent ¶

Alle Endpunkte antworten mit 404 Not Found, wenn der Plattformbetreiber KI-Funktionen instanzweit deaktiviert hat (AI_FEATURES_ENABLED=false) — die KI-API existiert dann faktisch nicht. Details zur dreistufigen Freischaltung: KI-Assistent — Benutzerhandbuch.

Öffentliche Wissensfrage (Light-Modus-fähig)¶

Kein Login nötig, IP-ratenbegrenzt (AI_PUBLIC_RATE_LIMIT_PER_MIN, Standard 10/Minute). Es wird kein Mandanten- oder Nutzerkontext an die Wissensbasis übergeben.

POST /api/v1/public/ai/ask

Request-Body:

Response (200): AiResponseSchema

{
  "answer_text": "VPD (Dampfdruckdefizit) beschreibt den Unterschied ...",
  "sources": [
    { "source_key": "vpd-basics", "source_type": "guide", "title": "VPD-Grundlagen", "score": 0.87, "language": "de" }
  ],
  "language": "de",
  "language_mismatch_warning": false,
  "uses_tenant_data": false,
  "uses_cloud_provider": false,
  "confidence": "high",
  "fallback_species": null,
  "cultivar_hint": null,
  "model_name": "gemma3:12b",
  "provider_type": "ollama",
  "kb_version": "ks-1.4.2-idx-20260420",
  "generated_at": "2026-07-11T10:15:00Z"
}

confidence ist einer von high | medium | low | none (ADR-002 — sinkt, wenn die Frage auf eine mandanteneigene Art/Sorte referenziert, die nicht in der Wissensbasis vorhanden ist).

GET /api/v1/public/ai/health

Response (200): { "healthy": true }

Mandantenbezogene Endpunkte¶

Alle folgenden Endpunkte liegen unter /api/v1/t/{tenant_slug}/ai/ und erfordern ein gültiges JWT-Token sowie eine aktive Mandanten-Mitgliedschaft. Eine rollenspezifische Einschränkung (Beobachter/Grower/Admin) ist in dieser Version noch nicht implementiert — jedes aktive Mitglied darf alle Endpunkte aufrufen.

POST /ai/explain erwartet folgenden Request-Body:

POST /ai/conversations/{conversation_key}/messages liefert die Antwort als text/event-stream (SSE) mit den Event-Typen token (einzelnes Antwort-Token), done (finale AiResponseSchema als JSON) und error.

Fehlercodes (alle mandantenbezogenen Endpunkte):

Globale Endpunkte (Platform-Admin)¶

GET /api/v1/ai/knowledge-service/health

Erfordert Platform-Admin-Rechte. Nur im Vollmodus gemountet (KAMERPLANTER_MODE=full). Liefert { "healthy": true|false }.

Siehe auch¶

• KI-Assistent — Benutzerhandbuch
• Datenschutz & DSGVO — Benutzerhandbuch
• Umgebungsvariablen — KI-Assistent
• Fehlerbehandlung

CV-Krankheitsdiagnose ¶

Bildbasierte Zustandsdiagnose (Krankheit, Nährstoffmangel, ergänzend Schädling) aus einem Blattfoto — abgegrenzt von der Artbestimmung (Pflanzenerkennung) und von der spezialisierten Schädlingserkennung: Diese Diagnose beantwortet „was fehlt der Pflanze?", nicht „welche Art/welcher Schädling ist das?". Die Erkennung läuft self-hosted im Inference-Service; das hochgeladene Foto wird serverseitig von EXIF-Metadaten bereinigt und nicht dauerhaft gespeichert — nur ein SHA-256-Fingerabdruck bleibt erhalten (image_deleted_at ist bei jeder Antwort gesetzt).

Alle Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/cv-diagnosis/ und erfordern ein gültiges JWT-Token. Lesende Endpunkte (/status, /history) benötigen keine besondere Mandanten-Rolle; schreibende Endpunkte (/diagnose, /diagnose/{request_key}/confirm) erfordern mindestens die Rolle grower.

Verfügbarkeit prüfen¶

GET /api/v1/t/{tenant_slug}/cv-diagnosis/status

Response (200): CvDiagnosisStatusResponse

{
  "available": false,
  "feature_enabled": false,
  "adapter_key": "local_cv_diagnosis",
  "phenotype_available": false,
  "class_count": 0
}

Foto-Diagnose durchführen¶

POST /api/v1/t/{tenant_slug}/cv-diagnosis/diagnose

Erfordert mindestens die Mandanten-Rolle grower — die Rolle viewer erhält 403. Die Einwilligung plant_diagnosis ist im Voll-Modus Pflicht und wird serverseitig geprüft (403 CONSENT_REQUIRED ohne erteilte Einwilligung); im Light-Modus entfällt die serverseitige Prüfung, da dort kein Consent-Subsystem existiert (siehe Datenschutz & DSGVO).

Request-Body: multipart/form-data

Query-Parameter:

Response (200): CvDiagnosisResponse

{
  "key": "plant_diagnosis_requests/abc123",
  "plant_instance_key": "plant_instances/101",
  "inspection_key": null,
  "classifications": [
    {
      "label": "septoria_leaf_spot",
      "category": "disease",
      "scientific_name": null,
      "probability": 0.74,
      "highlight": false,
      "matched_disease_key": "diseases/septoria",
      "matched_pest_key": null,
      "matched_symptom_slug": null
    }
  ],
  "phenotype": null,
  "model_meta": {
    "model_name": "kamerplanter-leaf-disease-v1",
    "training_base": "imagenet-dinov2-backbone",
    "fine_tuned_on": ["plantdoc-ccby4"],
    "onnx_checksum": "sha256:...",
    "model_version": "20260601",
    "class_count": 17
  },
  "adapter_key": "local_cv_diagnosis",
  "is_confident": false,
  "disclaimer": "Nur eine Einschätzung der Bilderkennung — keine gesicherte Diagnose. Bitte den Verdacht fachlich prüfen, bevor du behandelst; bei Unsicherheit einen zweiten Blick einholen.",
  "confirmed_labels": [],
  "image_hash": "sha256:9f86d0...",
  "image_deleted_at": "2026-07-11T14:30:02Z",
  "created_at": "2026-07-11T14:30:00Z"
}

Fehlercodes:

Diagnose zu einer IPM-Inspektionsvorlage bestätigen¶

POST /api/v1/t/{tenant_slug}/cv-diagnosis/diagnose/{request_key}/confirm

Erfordert mindestens die Mandanten-Rolle grower. Legt aus den bestätigten Klassen eine IPM-Inspektion als Vorschlag an — niemals automatisch eine Behandlung; das Karenz-Gate bleibt in jedem Fall aktiv.

Request-Body:

{
  "plant_key": "plant_instances/101",
  "confirmed_labels": ["septoria_leaf_spot"]
}

Response (201): ConfirmDiagnosisResponse

{
  "inspection_key": "inspections/42",
  "detected_disease_keys": ["diseases/septoria"],
  "detected_pest_keys": [],
  "confirmed_labels": ["septoria_leaf_spot"]
}

Fehlercodes:

Diagnose-Historie abrufen¶

GET /api/v1/t/{tenant_slug}/cv-diagnosis/history

Query-Parameter:

Response (200): Liste von CvDiagnosisResponse (siehe oben), sortiert nach Erstellungsdatum absteigend, beschränkt auf die eigenen Diagnosen des angemeldeten Nutzers im aktuellen Mandanten.

Lizenzhinweise¶

Der Klassifikator ist auf dem PlantDoc-Datensatz (CC-BY-4.0, Attribution) plus eigenen kuratierten Realdaten fine-getunt; die Phänotyp-Pipeline nutzt PlantCV (MPL-2.0, unverändert als Bibliothek). PlantVillage wird nicht verwendet (Lizenz ungeklärt). Vollständige Attributionstexte: NOTICE.md.

Siehe auch¶

• Meiner Pflanze geht es schlecht — Symptom-Diagnose
• Schädlingserkennung per Foto
• Pflanzenschutz (IPM)
• Datenschutz & DSGVO — KI-Krankheitsdiagnose
• Umgebungsvariablen — CV-Krankheitsdiagnose

Aquaponik ¶

Aquaponik führt Fisch-Pflanzen-Kreislaufsysteme ein: Fischbestand, Wassertests mit automatisch berechnetem freiem Ammoniak, Biofilter-Cycling-Erkennung, Fütterung und Nährstoff-Supplementierung. Das Frontend deckt bislang nur einen Teil der API ab (Systeme anlegen/auflisten, Wassertest erfassen, Einfahrfortschritt und Wasserqualität lesen) — siehe Aquaponik — Benutzerhandbuch: Für technische Nutzer / Self-Hoster für die vollständige, noch UI-lose Restfläche der API.

Mandantenspezifisch unter /api/v1/t/{tenant_slug}/aquaponics/ (28 Endpunkte, schreibende Aufrufe erfordern mindestens die Rolle grower, Systeme löschen erfordert admin):

Global (nicht mandantenspezifisch, keine Schreibrechte nötig) unter /api/v1/fish-species/:

Siehe auch¶

• Aquaponik — Benutzerhandbuch
• Tankmanagement — Benutzerhandbuch
• Fehlerbehandlung

Nacherntebehandlung (Post-Harvest)¶

Alle Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/post-harvest/ und erfordern ein gültiges JWT-Token. Lesende Endpunkte akzeptieren jede aktive Mitgliedschaft; schreibende Endpunkte erfordern mindestens die Rolle grower; das Löschen einer Charge ist admin-only.

Stufen-Zustandsmaschine: drying → curing → stored → released — ausschließlich vorwärts, ein Schritt je Aufruf. Der Übergang drying → curing erfordert zusätzlich dryness_progress_percent >= 95.

Fehlercodes:

Beispiel — Trocknung starten¶

curl -X POST \
  "https://api.example.com/api/v1/t/mein-garten/post-harvest/start-drying" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "harvest_batch_key": "harvest_batches/42",
    "species_type": "flower",
    "drying_method": "hang_dry",
    "target_moisture_percent": 10
  }'

Siehe auch¶

• Nacherntebehandlung — Benutzerhandbuch
• Ernte — Benutzerhandbuch
• Fehlerbehandlung

Umgebungssteuerung & Aktorik ¶

Alle Endpunkte liegen unter dem mandantenspezifischen Pfad /api/v1/t/{tenant_slug}/ und erfordern ein gültiges JWT-Token. Lesende Aufrufe akzeptieren jede aktive Mitgliedschaft; schreibende Aufrufe (Anlegen, Befehl, Override, Regeln, Zeitpläne, Notabschaltung) erfordern mindestens die Rolle grower; das Löschen eines Aktors erfordert admin. Die Oberfläche deckt bislang nur einen Teil der API ab (Aktor anlegen/auflisten/löschen, direkter Ein-/Aus-Befehl, Notabschaltung mit dem Szenario fire_alarm) — siehe Umgebungssteuerung & Aktorik — Benutzerhandbuch: Für technische Nutzer / Self-Hoster für die vollständige, noch UI-lose Restfläche der API (Zeitpläne, Regeln, phasengebundene Profile, Wertebereich-Konfiguration).

Sicherheitsgarantien¶

Wertebereich (Envelope): Jeder Befehl, Regel-Treffer, Zeitplan-Treffer und Override durchläuft denselben Chokepoint im Backend. Ein numerischer Wert für einen Aktor ohne konfigurierten min_value/max_value wird abgelehnt (422 bei einem direkten Befehl oder Override; bei der automatischen Regelschleife wird der betroffene Aktor übersprungen und protokolliert). Ist ein Wertebereich konfiguriert, wird jeder Wert automatisch auf [min_value, max_value] begrenzt (geklemmt) — auch nicht-endliche Werte (NaN/Infinity) werden dabei nie unverändert durchgereicht.

Zeitlich befristeter Override: POST /actuators/{key}/override erfordert expires_at als Pflichtfeld. Ein expires_at, das bereits in der Vergangenheit liegt, wird mit 422 abgelehnt — es gibt keine implizite Standarddauer.

POST /api/v1/t/mein-garten/actuators/act_42/override
{
  "expires_at": "2026-07-11T10:00:00Z",
  "override_state": "on",
  "reason": "Manuelle Belüftung vor dem Wochenende"
}

Antwort (422), wenn expires_at bereits abgelaufen ist:

{
  "error_id": "err_...",
  "error_code": "VALIDATION_ERROR",
  "message": "Manual override expires_at must be in the future.",
  "details": [],
  "timestamp": "2026-07-11T09:00:00.000000+00:00",
  "path": "/api/v1/t/mein-garten/actuators/act_42/override",
  "method": "POST"
}

Notabschaltung — Fehlertoleranz je Aktor: POST /emergency-stop behandelt jeden betroffenen Aktor isoliert. Scheitert das Schalten eines einzelnen Aktors (z. B. Home Assistant nicht erreichbar), bricht der Aufruf nicht ab — die Antwort listet erfolgreich geschaltete (stopped, forced_on) und fehlgeschlagene (failed) Aktor-Keys getrennt auf:

{
  "scenario": "fire_alarm",
  "stopped": ["act_1", "act_3"],
  "forced_on": [],
  "failed": ["act_2"]
}

Siehe auch¶

• Umgebungssteuerung & Aktorik — Benutzerhandbuch
• Sensorik — Benutzerhandbuch
• Umgebungsvariablen — Umgebungssteuerung & Aktorik
• Fehlerbehandlung

Phasendefinitionen: Pflanzen & Arten je Phase ¶

Zwei schlanke, rein lesende Endpunkte speisen die beiden zusätzlichen Listen auf der Phasendefinitions-Detailseite: welche eigenen Pflanzen sich gerade in einer Phase befinden, und welche Arten diese Phase im globalen Katalog grundsätzlich durchlaufen.

Arten für eine Phasendefinition auflisten (global)¶

Liefert alle Arten aus dem globalen Katalog, deren Phasenablauf die angegebene Phasendefinition enthält. Kein Mandanten-Präfix — Referenzdaten wie botanische Familien oder der Winterhärtezonen-Katalog.

GET /api/v1/phase-definitions/{key}/species

Erfordert ein gültiges JWT-Token, keine gesonderte Rollen-Einschränkung.

Pfad-Parameter: key — Schlüssel der Phasendefinition.

Response (200): Liste von PhaseDefinitionSpeciesResponse. Leer, wenn keine Art diese Phase durchläuft (kein 404).

[
  {
    "key": "species/123",
    "scientific_name": "Solanum lycopersicum",
    "common_names": ["Tomate", "Tomato"],
    "typical_duration_days": 30,
    "illustration": "phases/flowering.svg"
  }
]

Ist eine Art über mehrere Phasenabläufe mit derselben Phasendefinition verknüpft, erscheint sie nur einmal (dedupliziert nach Art-Schlüssel); eine gesetzte art-spezifische Überschreibung hat dabei Vorrang vor dem Standardwert der Definition.

Aktive Pflanzinstanzen des Mandanten in einer Phasendefinition auflisten¶

Liefert die aktiven Pflanzinstanzen des aufrufenden Mandanten, deren aktuelle Phase auf die angegebene Phasendefinition aufgelöst wird. Mandantengescopt (SEC-001) — ein leerer Mandanten-Kontext wird serverseitig abgelehnt, statt fremde Daten zu liefern.

GET /api/v1/t/{tenant_slug}/plant-instances/by-phase-definition/{phase_definition_key}

Erfordert ein gültiges JWT-Token und eine aktive Mandanten-Mitgliedschaft; jede Rolle darf lesen.

Response (200): PlantInstancesInPhaseResponse. items ist leer, wenn keine aktive Pflanze des Mandanten in dieser Phase ist (kein 404).

{
  "total": 2,
  "items": [
    {
      "key": "plant_instances/101",
      "instance_id": "T3-01",
      "plant_name": "Tomate Balkon",
      "species_key": "species/123",
      "species_scientific_name": "Solanum lycopersicum",
      "species_common_names": ["Tomate"],
      "location_key": "locations/5",
      "location_name": "Balkon Süd",
      "slot_key": "slots/12",
      "slot_label": "Reihe 2, Topf 3",
      "current_phase_key": "phase_sequence_entries/456",
      "current_phase_started_at": "2026-06-20T08:00:00Z"
    }
  ]
}

"Aktiv" bedeutet removed_on == null — entfernte Pflanzen (siehe Wachstumsphasen — Benutzerhandbuch: Eine Pflanze entfernen) erscheinen hier nicht. Die Zuordnung einer Pflanze zur Phasendefinition läuft über deren aktuelle Phasenablauf-Zuordnung (PhaseSequenceEntry.phase_definition_key); bei Altdaten ohne Phasenablauf greift zusätzlich ein Fallback über den gemeinsamen kanonischen Phasennamen einer Legacy-GrowthPhase.

Route-Reihenfolge: /by-phase-definition/{phase_definition_key} ist im Router vor /{key} deklariert, damit der literale Pfad nicht versehentlich als Pflanzen-Key interpretiert wird (dasselbe Muster wie bei /survival-stats, siehe oben).

Siehe auch¶

• Wachstumsphasen — Benutzerhandbuch: Detailansicht einer Phasendefinition
• Stammdaten: Pflanzenarten — Benutzerhandbuch
• Fehlerbehandlung