canonical: https://jentic.com/apis/mserver.io/mserver

# Mserver brainergy

The brainergy API exchanges energy-system data between Multiserver and the brainergy optimisation service, keyed by a system id in the URL path. Clients pull aggregated time series for a period and interval, choosing measurement, schedule, or forecast groups for named channels such as grid import and export, demand, or PV output. They push new time series and detected anomalies back for the same system, and read the key-value model parameters that describe components like electric storage. A health route reports whether the service is running.

## For AI agents

Pull and push measurement, schedule, and forecast time series for an energy system, submit anomalies, and read model parameters through the brainergy API.

## Scope

Does not control devices, run the optimisation itself, or bill energy usage. Use for exchanging time series, anomalies, and model parameters for an energy system only.

## Capabilities

- Pull aggregated measurement, schedule, or forecast time series for an energy system between periodStart and periodEnd at a chosen periodInterval
- Submit new time series values for named channels such as grid power or PV output on one energy system
- Report anomalies on a channel with begin and end timestamps and a percent value
- Read key-value model parameters for components such as electric storage on an energy system
- Check whether the brainergy service is running or unavailable

## Use cases

### AI energy-ops agent comparing schedule with measurement

An AI agent monitoring a site needs to know whether grid import is tracking the optimised schedule. Through Jentic the agent searches for 'pull time series for an energy system', loads the brainergy pull operation with its input schema, and requests both the measurement and schedule groups for the same grid channel over a period. It then reports where the measured values drift from the plan, with the bearer token injected at call time.

Example prompt: Call POST `/pullTimeseries/{systemId}` with periodStart, periodEnd, periodInterval=1h, and timeSeries entries for the measurement and schedule groups of electricPowerGrid-1.electricPowerMinus-1, then flag hours where they differ

### Uploading metered readings to the optimiser

A site gateway collects grid and PV readings and needs them in brainergy so the optimiser works from current data. The push route accepts a set of named series, each with a group, a name, and a map of timestamp to value, for one system id, so the gateway can send import, export, and generation together in one call.

Example prompt: Call POST `/pushTimeseries/{systemId}` with a timeSeries array holding measurement values for electricPowerGrid-1.electricPowerMinus-1 and pv-1.electricPowerPlus-1

### Flagging anomalies for review

When a detector spots a channel behaving oddly, such as a grid meter dropping to zero, it records the window and severity in brainergy. Each anomaly carries the channel name, begin and end timestamps, and a percent value, and several anomalies can be submitted for one system in a single request.

Example prompt: Call POST `/pushAnomalies/{systemId}` with an anomalies entry for electricPowerGrid-1.electricPowerMinus-1 from 14:00 to 14:01 UTC at 50 percent

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/pullTimeseries/{systemId}` | Retrieve aggregated time series for a system |
| POST | `/pushTimeseries/{systemId}` | Submit time series data for a system |
| POST | `/pushAnomalies/{systemId}` | Submit anomalies for a system |
| GET | `/parameters/{systemId}` | Retrieve model parameters for a system |
| GET | `/health` | Check service health |

## Key resources

- **Time series** — Pull aggregated or push raw measurement, schedule, and forecast series per energy system
- **Anomalies** — Submit anomaly windows with a channel name, begin, end, and percent
- **Parameters** — Read the key-value model parameters for an energy system's components
- **System** — Health check for the brainergy service

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 49 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 90 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 23 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 63 / 100
- **View full report:** https://jentic.com/apis/mserver.io/mserver/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring brainergy by hand means attaching a bearer token, building systemId paths, and assembling timeSeries payloads with group and channel names in the exact shape the optimiser expects. Through Jentic you install once, import brainergy from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** brainergy puts the system id in the URL path on every data route, such as `/pullTimeseries/{systemId}`, so a rule can pin your agent to one energy system and the operations you pick. Read-only routes can be allowed while the push routes for time series and anomalies are not included unless you add them.
- **Credential handling:** Your brainergy bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'pull time series for an energy system' or 'report an energy anomaly', and Jentic returns the matching brainergy operation with its input schema, including the required period and timeSeries fields, so the agent builds a valid request.

## Related APIs

- **Corrently Energy API** — Energy data API with grid and consumption information
- **Enphase Monitoring API** — Solar system production and consumption telemetry from Enphase installations
- **Solcast API** — Solar irradiance and PV power forecasts

## FAQ

### What authentication does the brainergy API use?

Per its OpenAPI spec, the brainergy API uses HTTP bearer authentication, declared on all five operations including the health check, with the token sent as Authorization: Bearer. Through Jentic the token is held by your own instance and attached when each call runs, so the agent never sees it.

### Can I pull forecasts and measurements in one request with the brainergy API?

Yes. POST `/pullTimeseries/{systemId}` takes a required periodStart, periodEnd, periodInterval, and a timeSeries array, and each entry names a group such as measurement, schedule, or forecast plus a channel name. The response returns one series per entry with a map of timestamps to values.

### What are the rate limits for the brainergy API?

The OpenAPI spec does not specify rate limits. The spec is published on SwaggerHub at https://api.swaggerhub.com/apis/RENESTEINERAT1/brainergy/0.2.0, so check with the Multiserver operator of your instance for current limits.

### How do I push meter readings to brainergy through Jentic?

Search Jentic for 'submit time series for an energy system', load the POST `/pushTimeseries/{systemId}` operation, and execute it with the system id and a timeSeries array of named series and timestamp-value maps. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the brainergy API?

Yes. Write a rule that allows only the pull time series and model parameters operations for one systemId, such as system 42, and the agent can read that site's series and parameters but cannot push data or anomalies, or reach another system. Every call it makes is logged.

### Which host does the brainergy API use?

The spec declares a single server, https://schulung.mserver.io/brainergy/v1, which is a training host. A production Multiserver deployment may expose brainergy on a different host, so confirm the base URL with your operator.