The Demeter REST API is self-documenting via an OpenAPI 3.1 specification generated from the route schemas at runtime. This page is the entry point; the authoritative, always-current reference is the generated spec itself.
Where the docs live#
| Resource | URL | Notes |
|---|---|---|
| Interactive Swagger UI | GET /docs |
Try-it-out console, filter, deep links |
| OpenAPI 3.1 JSON | GET /docs/json |
Machine-readable; feed to client/codegen tooling |
Both are wired in apps/demeter/api/src/plugins/swagger.ts (@fastify/swagger
@fastify/swagger-ui), registered inbuildServer()before the routes so the spec captures every endpoint's schema.
Versioning#
All resource endpoints live under the /v1 prefix. Health probes (/health,
/health/ready) are unversioned. The spec's info.version tracks the API
package version.
Authentication#
Most endpoints require a Bearer JWT (declared as the BearerAuth security
scheme in the spec):
Authorization: Bearer <access-token>
Obtain a token via POST /v1/auth/login (or the OAuth / magic-link flows under
/v1/auth/*). IoT clients may instead present an API key — see the /v1/auth
API-key endpoints. Tokens rotate via refresh tokens with family-based reuse
detection.
Documented domains#
The spec is tagged by feature area; each tag groups its endpoints in the UI:
| Tag | Prefix | Covers |
|---|---|---|
| Health | /health |
Liveness / readiness probes |
| Gardens | /v1/gardens |
Gardens, beds, membership/sharing |
| Plants | /v1/plants |
Plant database, companion planting |
| Plantings | /v1/plantings |
Seed-to-harvest lifecycle tracking |
| Tasks | /v1/tasks |
Maintenance task scheduling & completion |
| Harvests | /v1/harvests |
Harvest recording, yield analytics |
| Sensors | /v1/sensors |
IoT sensors + time-series readings |
| Weather | /v1/weather |
Weather data, forecasts, frost alerts |
| Observations | /v1/observations |
Field notes & photo documentation |
| (AI) | /v1/ai |
Algorithmic recommendations & inference |
| (Community) | /v1/community |
Posts, comments, challenges, leaderboard |
Exporting the spec#
To produce a static openapi.json for SDK generation or publishing, boot the
server and fetch the JSON:
pnpm --filter @demeter/api dev & # or: build && start
curl -s http://localhost:3000/docs/json > openapi.json
Guarantees (enforced by tests)#
test/integration/openapi.integration.spec.ts fails the build unless the
generated spec stays complete: OpenAPI 3.1, the BearerAuth scheme, all domain
tags, ≥ 20 documented paths, and — critically — every operation carries a
summary, a tag, and at least one response. A new endpoint that ships without
schema annotations breaks this test, so the reference can never silently drift
out of date.