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¶

Getting the OpenAPI schema¶

There are three ways to get the OpenAPI document — which one fits depends on who needs it and what for:

Every published release attaches the current OpenAPI document under the stable, version-less name openapi.json. This naming is a deliberate choice: it is the only way the permanent link releases/latest/download/openapi.json keeps working and always resolves to the most recently published version.

To pin to a specific version instead, download the asset from the releases overview of the desired tag — releases published before this asset was introduced do not include it.

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)
• MCP Server — external LLM clients as a Kamerplanter tool
• Local Development Setup — Running the backend locally