Fentrica Help Center

Expert Guide

Advanced configuration for AI optimizers and complex systems.

Edge Device REST API

Send a command to a Fentrica edge device (controller) over HTTPS, authenticated with an API key — no human login required. This is the server-to-server counterpart to Cloud Device Connection, which uses a WebSocket and a user token; here a single REST call carries one command and returns the device's reply.

Prerequisites

  • Your organization id (orgId) and the target device id (deviceId).
  • An API key with the Edge devices → read & write scope, covering the site the device belongs to (organization-wide, or scoped to that site). See API Keys to create one.

The command envelope

Every device command uses the same endpoint; the command name goes in the path:

POST https://broker.fentrica.com/api/orgs/{orgId}/larva-device-admin/{deviceId}/cmd/{command}

Headers:

HeaderValue
X-Api-Keyyour key, lrv_…
Content-Typeapplication/json

Request body:

{
  "data": {},
  "reqId": "d3b07384-d9a0-4c9b-8f1e-2f4a6c8e0b12"
}
  • data — the command's payload (shape depends on the command).
  • reqId — optional UUID you supply to correlate the response; it is echoed back.

Response — the device's reply:

{
  "reqId": "d3b07384-d9a0-4c9b-8f1e-2f4a6c8e0b12",
  "data": {}
}
StatusMeaning
200Command delivered; body is the device reply.
401Missing or invalid API key.
403Key lacks the edge-device:read_write scope, or is not authorized for this organization or the device's site.
502The device or the device gateway is offline.

Your first call — getTechnicalConnectionStatus

getTechnicalConnectionStatus returns the live status of a technical connection on the device. Its data is { "id": "<technicalConnectionId>" }.

curl -X POST \
  'https://broker.fentrica.com/api/orgs/{orgId}/larva-device-admin/{deviceId}/cmd/getTechnicalConnectionStatus' \
  -H 'X-Api-Key: lrv_…' \
  -H 'Content-Type: application/json' \
  -d '{ "data": { "id": "<technicalConnectionId>" } }'

The same call with fetch:

const res = await fetch(
  `https://broker.fentrica.com/api/orgs/${orgId}/larva-device-admin/${deviceId}/cmd/getTechnicalConnectionStatus`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.FENTRICA_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ data: { id: technicalConnectionId } }),
  },
);
const { data } = await res.json(); // data = the connection's live status value

Command catalog

The commands below are a starter set.

CommandDescriptionRequest dataResponse
getTechnicalConnectionStatusLive status of a technical connection{ "id": "<technicalConnectionId>" }The connection's current status value
getTechnicalDataPointsDatapoint configuration on a connection{ "connectionId": "…", "limit": 50, "offset": 0 }{ "datapoints": [...], "count": n }
getTechnicalConnectionValuesLive value of every datapoint on a connection, in one call{ "id": "<technicalConnectionId>" }{ "connectionId", "status", "error", "timestamp", "values": {...} }
demandResponseOverridePlace a bounded Demand Response / aFRR setpoint on a datapoint{ "datapointId": "…", "value": -25, "from": "<ISO>", "to": "<ISO>" }{ "id": "<overrideId>" }
demandResponseCancelRelease a Demand Response window early{ "id": "<overrideId>" }{ "success": true }

For a worked end-to-end integration using the last four — including example responses, precedence rules and the audit trail — see Demand Response Provider Integration.

The full edge-device command set is not listed here. To request the complete command reference for your integration, contact [email protected].

Errors & troubleshooting

  • 401 — check the X-Api-Key header is present and the key has not been revoked.
  • 403 — the key needs Edge devices → read & write covering the device's site; an organization-wide grant always qualifies. Also confirm the {orgId} in the path matches the key's organization.
  • 502 — the device or gateway is offline; retry once it reconnects.
  • Include a unique reqId on each request and match it against the response to correlate calls in your logs.

See also