API Overview¶

The Kamerplanter API is a REST API built on FastAPI. All endpoints return JSON and follow standard HTTP conventions. An interactive Swagger UI is available at /api/v1/docs.

Base URL¶

http://localhost:8000/api/v1

In production environments, the API is exposed through Traefik as the ingress controller under the configured domain.

Interactive Documentation¶

Deployment Modes¶

The API behaviour depends on the configured deployment mode. The current mode is exposed by the mode endpoint:

GET /api/v1/mode

{
  "mode": "full",
  "features": {
    "auth": true,
    "multi_tenant": true,
    "privacy_consent": true
  }
}

full (Default)¶

Full operation with authentication, multi-tenancy, and GDPR features. All auth endpoints are active. Every request must be authenticated (except health, mode, and public OAuth callbacks).

light¶

Enabled via KAMERPLANTER_MODE=light. No login required — all endpoints are accessible without authentication. Suitable for local single-user installations without multi-tenant requirements. The auth routers (/auth/...) are disabled in this mode.

URL Structure¶

The API distinguishes between global resources and tenant-scoped resources.

Global Resources¶

Master data such as plant species, botanical families, and IPM reference data is global — it does not belong to any single tenant.

GET  /api/v1/species/
GET  /api/v1/species/{key}
GET  /api/v1/botanical-families/
GET  /api/v1/cultivars/
GET  /api/v1/ipm/pests/
GET  /api/v1/starter-kits/

Tenant-Scoped Resources¶

All user-specific data (plants, runs, sensors, tanks, etc.) belongs to a tenant and is addressed via the tenant slug in the URL:

/api/v1/t/{tenant_slug}/...

Examples:

GET  /api/v1/t/my-garden/plant-instances/
POST /api/v1/t/my-garden/planting-runs/
GET  /api/v1/t/my-garden/tanks/
GET  /api/v1/t/my-garden/tasks/

The tenant slug is automatically generated from the username at registration (personal tenant). For community gardens a separate tenant can be created.

Health Endpoints¶

Health endpoints require no authentication and are intended for Kubernetes liveness and readiness probes:

GET /api/v1/health/live    → {"status": "alive"}
GET /api/v1/health/ready   → {"status": "ready", "database": true}

Endpoint Groups¶

The following table lists all available router groups. In full mode, auth, oidc-providers, and platform-admin routes are additionally active.

Global Endpoints¶

Tenant-Scoped Endpoints (/t/{slug}/...)¶

Admin Endpoints¶

The plant identification settings endpoints are exclusively accessible to users with the platform role admin. The key is never returned in plain text in any response.

Request and Response Format¶

All request bodies and responses use application/json. An explicit Content-Type: application/json header is required for POST/PUT/PATCH requests.

Pagination¶

List endpoints support skip and limit as query parameters:

GET /api/v1/species/?skip=0&limit=50

Defaults: skip=0, limit=100 (varies by endpoint).

Date Format¶

All dates and timestamps follow ISO 8601 in UTC:

2026-03-17T10:30:00Z

Rate Limiting¶

Sensitive endpoints are rate-limited to prevent abuse:

When exceeded, the API responds with HTTP 429 Too Many Requests.

CORS Configuration¶

Allowed origins are configured via the CORS_ORIGINS environment variable as a comma-separated list:

CORS_ORIGINS=https://app.kamerplanter.example.com,https://admin.kamerplanter.example.com

By default, http://localhost:3000 and http://localhost:5173 (Vite dev server) are allowed.

Security Headers¶

Every API response includes the following security headers:

See Also¶

• Authentication — Token workflow and API keys
• Error Handling — Error structure and error codes
• Service Accounts — M2M access (planned, not yet implemented)
• Local Development Setup — Running the backend locally