> For the complete documentation index, see [llms.txt](https://docs.myrspoven.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myrspoven.com/developers/reports-api.md).

# Reports API

The Reports API lets a partner read the status of their buildings into their own system: which buildings are connected, what state each is in, how much of the time myCoreAI was in control, which equipment it steers, and which alerts are open. A typical use is showing Myrspoven status inside a building operations platform such as Schneider EcoStruxure Building Operation (EBO), where buildings can also be looked up by their EBO system ID.

The Reports API is read-mostly. The only thing a partner can write through it is a small set of building properties, such as the EBO system ID a building belongs to. It does not read or write setpoints: that is the job of the [Myrspoven AI-API](https://docs.myrspoven.com/developers/myrspoven-ai-api.md).

## Getting access

Myrspoven sets up API access for your company during onboarding and gives you:

* **Client credentials:** a client ID and secret, shared through a secure channel, never over email or chat.
* **Token endpoint and base URL:** the address of the identity provider to request tokens from, and the address of the Reports API.

Credentials are tied to your company. Every request only reaches the buildings that belong to that company.

## Authentication

The Reports API uses OAuth2 with the client credentials flow:

1. Request an access token from the token endpoint with your client ID and secret.
2. Send the token on every request in the `Authorization: Bearer <token>` header.
3. Request a new token when it expires.

A request without a valid token is answered with `401 Unauthorized`. A valid token that lacks access to the Reports API is answered with `403 Forbidden`. A credential that is not linked to a company reaches no buildings: building lists come back empty and requests for a single building answer `404 Not Found`.

## Versioning

The current version is **v1**. The version is chosen with the `x-api-version` request header. Requests without the header get v1, so a v1 client does not need to send it. Responses list the supported versions in the `api-supported-versions` header. Paths carry no version number.

## Access to buildings and systems

A client only sees its own company's buildings, and an EBO system ID only resolves to that company's buildings within the system.

A request for a building or system the client may not access answers `404 Not Found`, the same as for one that does not exist. The API does not reveal whether a building outside your company exists.

## Response format

Responses are JSON. Successful reads wrap their data in a `payload` field; building lists also carry a `count`. Enumerated values (building state, alert level and so on) are sent as text, for example `"Optimization"` or `"Warning"`. Times are in UTC.

Clients that send `Accept-Encoding: gzip` get gzip-compressed responses. Clients that don't get the same responses uncompressed.

## Endpoints

### Buildings

| Request                                  | Returns                                                                                                                     |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `GET /Buildings`                         | Every building your company has access to. Add `?eboSystemId=<id>` to list only the buildings in one EBO system.            |
| `GET /Buildings/{buildingId}`            | One building.                                                                                                               |
| `GET /Buildings/{buildingId}/AiStatus`   | myCoreAI's status hour by hour for one building.                                                                            |
| `GET /Buildings/{buildingId}/Components` | The heating, cooling and ventilation equipment in the building and how much myCoreAI steered each part over the last month. |
| `GET /Buildings/{buildingId}/Alerts`     | The building's current alerts.                                                                                              |

Each building has these fields:

| Field           | Meaning                                                                                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | The building's ID at Myrspoven. Use it in the other requests.                                                                                                                                  |
| `eboSystemId`   | The EBO system the building is linked to, in lower case. Empty when the building isn't linked to one.                                                                                          |
| `name`          | The building's name.                                                                                                                                                                           |
| `buildingState` | Where the building is in its life cycle with Myrspoven: `Startup`, `DataCollection`, `Optimization` (myCoreAI is optimizing it), `Offline` or `Closed`. `Default` means no state has been set. |
| `squareMeters`  | Floor area in m², if known.                                                                                                                                                                    |
| `timezone`      | The building's time zone, for example `Europe/Stockholm`.                                                                                                                                      |
| `countryCode`   | The building's country.                                                                                                                                                                        |
| `coordinates`   | `latitude` and `longitude`, as text.                                                                                                                                                           |

### AI status

`GET /Buildings/{buildingId}/AiStatus` returns one entry per hour with:

* **`hourlyStartTime`, `hourlyEndTime`:** the hour the entry covers.
* **`operationStatus`:** `Active` when myCoreAI was in control for at least 75 % of the hour, otherwise `Inactive`.
* **`optimizerStatus`:** `Enabled` or `Disabled` for whether AI control was on during the hour, or `Unknown` when no status was recorded for that hour.

`reportStartDate` and `reportEndDate` give the period the entries actually cover.

The optional `startDate` and `endDate` query parameters choose the period. Without them the report covers the last month up to today. Data goes back up to two years. A date further back or in the future is ignored, and so is an end date before the start date. With only a start date, the period runs one month from it, ending today at the latest.

A building that is not set up for AI status reporting answers `400 Bad Request`.

### Components

`GET /Buildings/{buildingId}/Components` returns the building's heating, cooling and ventilation systems. Each system has a `name` and a list of components with:

* **`name` and `type`:** the component and what kind of equipment it is.
* **`isEnabled`:** whether AI control is switched on for the component's main control point.
* **`aiStatusPercentage`:** the share of the last month, 0 to 100, that myCoreAI steered the component. Where the component has no status of its own, the building's AI status is used.

A building without any of these components answers `404 Not Found`.

### Alerts

`GET /Buildings/{buildingId}/Alerts` returns a list of alerts with `buildingId`, `type`, `level`, `message` and `timestamp`. Two optional query parameters filter the list:

* **`type`:** today the only type is `Fallback`: the building is in, or approaching, [safe mode](https://docs.myrspoven.com/getting-started/glossary#safe-mode).
* **`minimumLevel`:** `Unknown`, `Ok`, `Warning` or `Error`. Only alerts at that level or higher are returned.

### Systems (EBO)

These requests answer the same questions for all of your buildings in one EBO system at once. The `eboSystemId` is the system ID shown in EBO; upper and lower case are treated the same. A system with none of your buildings in it answers `404 Not Found`.

| Request                                 | Returns                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /Systems/{eboSystemId}/Buildings`  | The buildings in the system, with the same fields as above.                                                                                                                                                                                                                                                                                                   |
| `GET /Systems/{eboSystemId}/AiStatus`   | For each building in `Optimization`: `id`, `name`, `squareMeters`, the reporting period (`startDate`, `endDate`) and `percentage`, the share of hours with AI control enabled. Other buildings are listed separately under `nonOptimizedBuildings` with `id`, `name` and `squaredMeters`. Accepts the same `startDate` and `endDate` as the building request. |
| `GET /Systems/{eboSystemId}/Components` | Totals over all buildings: the number of `components`, how many were steered at least 75 % of the last month (`optimizedComponents`) and how many less (`partiallyOptimizedComponents`), and the average `aiStatusPercentage`.                                                                                                                                |
| `GET /Systems/{eboSystemId}/Alerts`     | The alerts of every building in the system, with the same filters as the building request.                                                                                                                                                                                                                                                                    |

A building in `Optimization` that has no hourly AI status for the period is reported with 0 %.

### Building properties

A partner can read and set a small set of properties on its own buildings.

| Request                                                    | Does                                                                                                                      |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `GET /Properties/Definitions`                              | Lists the properties a partner can set, each with `propertyId`, `propertyType`, `displayName`, `description` and `group`. |
| `GET /Properties/{buildingId}/TextProperties`              | Returns the building's EBO system ID property.                                                                            |
| `GET /Properties/{buildingId}/TextProperties/{propertyId}` | Returns one property value.                                                                                               |
| `POST /Properties/{buildingId}/TextProperties`             | Adds a property value. Send `propertyId` and `value`; the answer is `201 Created`.                                        |
| `PUT /Properties/{buildingId}/TextProperties`              | Changes an existing value, with the same body; the answer is `204 No Content`.                                            |

The properties a partner can set are the building's EBO system ID and its carbon factors for heating, cooling, electricity and gas. A value that fails validation, or a property that isn't in the list, answers `400 Bad Request` with an `errors` list naming the field and the problem.

## Errors

Errors use the standard problem details format: a JSON body with `status`, `title` and `detail`, and `instance` where it applies.

| Status                      | When                                                                                                     |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | The request is invalid, or the building isn't set up for the report asked for.                           |
| `401 Unauthorized`          | The token is missing, expired or invalid.                                                                |
| `403 Forbidden`             | The token is valid but lacks access to the Reports API.                                                  |
| `404 Not Found`             | The building or system doesn't exist or isn't yours, or has nothing to report.                           |
| `429 Too Many Requests`     | More than 500 requests in one minute from the same IP address. Wait and retry.                           |
| `500 Internal Server Error` | Something failed on Myrspoven's side. The body carries a `TraceId`; quote it when you contact Myrspoven. |

## Data freshness

AI status and component figures are recalculated once a day, at midnight UTC, so they cover the period up to the end of the previous day. Alerts can be up to an hour old. Polling more often than that returns the same data.

## Getting help

Contact Myrspoven for credentials, for the base URL, or if a building is missing from an EBO system. Include the `TraceId` from any error response.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myrspoven.com/developers/reports-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
