API Reference¶

For interactive API docs with a running backend:

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

Print & Export (REQ-032)¶

All print endpoints are located under the tenant-scoped path /api/v1/t/{slug}/print/ and require a valid JWT token. Access rights mirror the permissions of the underlying data (REQ-024 RBAC) — anyone who may read a nutrient plan may also print it.

Common query parameters (all endpoints):

Nutrient Plan PDF¶

Exports a complete nutrient plan as a PDF including the phase table, mixing instructions, water configuration, and CalMag / flushing notes.

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

Path parameters:

Response: application/pdf with Content-Disposition: attachment; filename="nutrient-plan-{plan_key}.pdf"

Example:

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

Care Checklist PDF¶

Exports all due care tasks for a given date as a checklist with tick boxes, grouped by urgency (overdue, due today, coming up).

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

Query parameters (in addition to locale and format):

Response: application/pdf with Content-Disposition: attachment; filename="care-checklist-{date}.pdf"

Example:

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

Plant Info Cards / Label PDF¶

Prints compact info cards with a QR code for one or more plant instances. The QR code contains the deep-link URL to the respective plant in the app.

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

Query parameters (in addition to locale):

Possible values for fields:

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

The QR code is always included and cannot be deselected via fields.

Response: application/pdf with Content-Disposition: attachment; filename="plant-labels.pdf"

Example — 8 cards per A4 page with plant name, scientific name and planting date:

curl -X GET \
  "https://api.example.com/api/v1/t/my-garden/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=en" \
  -H "Authorization: Bearer <token>" \
  --output labels.pdf

Error codes:

List Available Templates¶

Returns a list of all registered print templates.

GET /api/v1/print/templates

This endpoint is not tenant-scoped and only requires a valid authentication token.

Example response:

[
  {
    "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 Notifications¶

All three endpoints are located under the tenant-scoped path /api/v1/t/{tenant_slug}/notifications/pwa/ and require a valid JWT token.

Retrieve the VAPID Public Key¶

Returns the instance's VAPID public key. The browser requires this key to create a push subscription.

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

Response (200):

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

If no VAPID key pair is configured, the endpoint responds with 503 Service Unavailable.

Register a Push Subscription¶

Registers the current device for browser push notifications. The subscription data is provided by the browser after calling PushManager.subscribe().

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

Request body:

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

Response: 201 Created on success, 409 Conflict if the subscription for this device is already registered.

Deregister a Push Subscription¶

Removes the subscription for the current device. After this, no browser push notifications will be sent to that device.

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

Request body:

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

Response: 204 No Content on success, 404 Not Found if the subscription was not found.

See Also¶

• Print Views & Export — User Guide
• Fertilization Logic
• Care Reminders
• Environment Variables — Browser Push (VAPID)