This guide is for third-party developers building an application or integration on top of Demeter's REST API. (If instead you're connecting a commercial device/hub into Demeter, see the integration guide.)
Start from the spec#
The API is OpenAPI 3.1 and self-documenting:
- Explore:
GET /docs(Swagger UI). - Codegen:
GET /docs/json— feed the spec toopenapi-typescript,openapi-generator, or similar to generate a typed client.
All resource endpoints are under /v1; see the
API reference.
Authenticate#
Two credential types:
| Use case | Credential |
|---|---|
| Acting as a user (web/mobile-style) | Bearer JWT from POST /v1/auth/login (refresh via the rotation flow) |
| Machine-to-machine / backend integration | API key (scoped permissions, Authorization header) |
Request only the permissions you need — API keys are scoped, stored hashed, and revocable (see ADR-0004).
Be a good client#
- Versioning: target
/v1; the spec'sinfo.versiontracks releases (see changelog & versioning). - Refresh handling: access tokens are short-lived. Store the newest refresh
token (rotation issues a fresh one each use); retry a
401once after refreshing. A reused/revoked refresh token revokes the whole family — treat that as "re-authenticate". - Rate limits: expect
429under burst; honourRetry-Afterand back off. Don't disable limits — design for them. - Validation: requests are Zod-validated; a
400means fix the payload, a404on a malformed id means the id wasn't a valid UUID.
Typical flows#
- Read a user's gardens:
GET /v1/gardens(Bearer). - Ingest external readings:
POST /v1/sensors/:id/readings(API key) — match theNormalizedReadingshape. - Pull harvest analytics:
GET /v1/harvests+/v1/analyticsendpoints.
Support#
The OpenAPI spec is the contract; the data-models doc explains request/response shapes and the row↔DTO conventions.