Skip to content

For integrators

These documents describe the message formats a controller must send to connect to Feldmelder Cloud: the Tracker Telemetry Protocol (MQTT with TLS client certificates), the plant geometry file and the JSON schemas used to validate every message. The REST API gives access to your own data with scoped tokens.

Tracker Telemetry Protocol TTP v1 (specification)

Topics, message envelope, sequence numbers, store-and-forward, enrolment and signed commands.

Plant geometry format

How a plant and its trackers are described (plant-geometry/1).

REST API v1 (OpenAPI)

Machine-readable description of the API for plants, trackers, time series and alarms.

REST API v1 1.2.0

openapi.json

Base URL: https://app.feldmelder.de/api/v1. Read-only overview of the OpenAPI document; the authoritative description is openapi.json.

auth

  • POST /auth/login 200 400 401 403 429
    Sign in and create an app session
    body: device_name, email, password, platform, totp
  • POST /auth/refresh 200 401
    Exchange a refresh token for new tokens (the old refresh token becomes invalid)
    body: refresh_token
  • POST /auth/logout 200 401 403
    Sign this device out (revokes the session and its push registration)

app

  • GET /me 200 401
    Profile, memberships, current organisation, scopes and push preferences
    X-Tenant-Id
  • PUT /me/push-preferences 200 400 403
    Set which alarms are pushed to this user's devices
  • GET /me/sessions 200 403
    Signed-in devices (app sessions) of this user; the calling device is marked current
  • DELETE /me/sessions/{session_id} 200 403 404
    Sign another device of this user out (as "Abmelden" on the profile page)
    session_id
  • POST /devices 200 400 403
    Register this device for push notifications (Firebase Cloud Messaging token)
    body: platform, push_token
  • DELETE /devices 200 403
    Remove this device's push registration

plants

  • GET /plants 200 401
    Plants of the organisation
    X-Tenant-Id, limit, offset
  • GET /plants/summary 200 401
    Plants with status, tracker count, open alarms and time of the last data
    X-Tenant-Id, limit, offset
  • GET /plants/{plant_id} 200 404
    One plant
    plant_id, X-Tenant-Id
  • GET /plants/{plant_id}/trackers 200 404
    Trackers of a plant
    plant_id, X-Tenant-Id, limit, offset
  • GET /plants/{plant_id}/latest 200 404
    Latest state of every tracker and controller of a plant
    plant_id, X-Tenant-Id
  • GET /trackers/{tracker_id} 200 404
    One tracker
    tracker_id, X-Tenant-Id
  • GET /trackers/{tracker_id}/latest 200 404
    Latest state of one tracker
    tracker_id, X-Tenant-Id
  • GET /trackers/{tracker_id}/series 200 400 404
    15-minute aggregates of one tracker (at most 31 days)
    tracker_id, X-Tenant-Id, from, to

alarms

  • GET /alarms 200 401
    Alarms (open, acknowledged, closed), newest first
    X-Tenant-Id, state, severity, plant_id, since, limit, offset
  • GET /alarms/{alarm_id} 200 404
    One alarm (target of a tapped push notification, data field alarm_id)
    alarm_id, X-Tenant-Id
  • POST /alarms/{alarm_id}/ack 200 403 404 409
    Acknowledge an open alarm (scope alarms:ack; app users with the acknowledge right)
    alarm_id, X-Tenant-Id · body: comment

commands

  • GET /plants/{plant_id}/commands 200 404
    Command history of a plant
    plant_id, X-Tenant-Id, limit, offset
  • POST /plants/{plant_id}/commands 202 400 401 403 409
    Send a signed stow or release (back to sun tracking) command – app tokens only, fresh TOTP code
    plant_id, X-Tenant-Id · body: totp, trackers, type
  • GET /commands/{cmd_id} 200 404
    One command with its acknowledgement
    cmd_id, X-Tenant-Id

devices-enrollment

  • GET /openapi.json 200
    This document as JSON (server URL of the installation)
  • POST /enroll 200 202 400
    Controller enrolment with a claim code and a CSR (TTP v1, docs/protocol/ttp-v1.md)
  • GET /enroll/{enrollment_id} 200 202 404
    Poll a pending enrolment (header X-Enroll-Token)
    enrollment_id, X-Enroll-Token

JSON schemas

alarm.schema.jsoncmd.schema.jsoncmd_ack.schema.jsonenroll_request.schema.jsonenroll_response.schema.jsonheartbeat.schema.jsonplant_geometry.schema.jsontracker_state.schema.jsonweather.schema.json