> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trlyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# terralayr API

> Build integrations with the terralayr platform — manage virtual assets, participate in auctions, report on revenue, and monitor physical assets.

The terralayr API gives your organisation programmatic access to the terralayr platform across six domains: virtual assets, auctions, revenue reporting, physical assets, asset monitoring, and authentication. Every endpoint is secured with a Bearer token — see [Authentication](#authentication) to get started.

<CardGroup cols={2}>
  <Card title="Virtual Assets" icon="battery-full" href="/virtual-assets-api-reference">
    Manage virtual batteries and their block schedules
  </Card>

  <Card title="Auctions" icon="gavel" href="/auctions-api-reference">
    Browse energy auctions, submit bids, and track outcomes
  </Card>

  <Card title="Revenue Reporting" icon="chart-line" href="/revenue-reporting-api-reference">
    Query revenue and aggregated data points across assets and portfolios
  </Card>

  <Card title="Physical Assets" icon="bolt" href="/physical-assets-api-reference">
    Manage physical asset parameters, schedules, bids, and logbook entries
  </Card>

  <Card title="Asset Monitoring" icon="wave-pulse" href="/monitoring-api-reference">
    Retrieve timeseries datapoints for physical assets
  </Card>

  <Card title="Authentication" icon="lock" href="/auth-api-reference">
    Authenticate and obtain Bearer tokens
  </Card>
</CardGroup>

***

## Virtual Assets

A **virtual asset** is a virtual battery with static parameters that control how much power it can import and export, how much energy it can store, and how efficiently it charges and discharges. It also has a state of charge that changes as the asset exports and imports power.

A **block** represents a slice of a virtual asset's power capacity over a time window. Each block has a schedule you can update to control what the virtual asset does during that period.

<Info>
  Keep virtual assets balanced: manage schedules so that the state of charge at the end of the asset's lifetime is 50%. You can submit schedules that deviate from this, but the response will include an imbalance report.
</Info>

***

## Auctions

This API lets participating organisations browse energy auctions, submit bids, and track outcomes on the terralayr platform.

Each auction offers a virtual-asset delivery window — power, energy, and efficiency parameters — for a specific period. During the auction open interval, invited organisations can place bids priced in EUR. After the auction closes, the highest valid bid wins; if prices tie, the earliest bid wins.

Auction responses include a status for your organisation:

| Status              | Meaning                                                |
| ------------------- | ------------------------------------------------------ |
| `NOT_STARTED`       | The auction has not yet opened                         |
| `RUNNING`           | The auction is open and accepting bids                 |
| `PENDING`           | The auction has closed and results are being processed |
| `WON`               | Your organisation won the auction                      |
| `LOST`              | Your organisation did not win                          |
| `NO_BIDS_SUBMITTED` | The auction closed with no bids from your organisation |

When you win, the response includes the allocated virtual asset ID.

***

## Revenue Reporting

This API exposes revenue data and aggregated data points for virtual assets, portfolios, fleets, and physical assets on the terralayr platform.

Use the revenue endpoints to query wholesale, ancillary, tolling, and virtual battery auction revenue for a virtual asset over a time range. Data-point endpoints return aggregated metrics at raw, 15-minute, hourly, or daily resolution.

### Data point categories

Data-point endpoints accept an optional `datapoints` query parameter: a comma-separated list of category names. When omitted, all categories for the asset are returned. Each category name appears as a key under `data` in the response (`dataPointName` in `metaData`).

#### Total and wholesale

Wholesale metrics are calculated per 15-minute delivery period. **Buy** means energy imported (charging); **sell** means energy exported (discharging). Volume-weighted average prices (VWAP) are the average wholesale price weighted by traded volume within each period. Net volume is sell minus buy energy (MWh). Net-off volume is the portfolio schedule-netting volume: energy attributed to internal schedule netting rather than wholesale market trades.

| Category                   | Description                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| `revenue_total_revenue`    | Total revenue across wholesale, ancillary, tolling, and virtual battery auction products |
| `revenue_wholesale`        | Wholesale market revenue for the period (sell proceeds minus buy cost)                   |
| `buy_vwap_wholesale`       | Volume-weighted average buy price over the 15-minute period (EUR/MWh)                    |
| `sell_vwap_wholesale`      | Volume-weighted average sell price over the 15-minute period (EUR/MWh)                   |
| `buy_volume_wholesale`     | Energy bought on the wholesale market in the period (MWh)                                |
| `sell_volume_wholesale`    | Energy sold on the wholesale market in the period (MWh)                                  |
| `net_volume_wholesale`     | Net wholesale energy: sell volume minus buy volume (MWh)                                 |
| `net_off_volume_wholesale` | Schedule-netting volume from portfolio internal netting (MWh)                            |

#### FCR

FCR metrics relate to 4-hour EFA delivery blocks. Weighted capacity and settlement price values multiply each accepted capacity or price by its delivery hours within the block. The weighted-average categories divide those sums by total delivery hours in the block.

| Category                            | Description                                                               |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `revenue_fcr`                       | FCR capacity revenue for the delivery window                              |
| `capacity_fcr`                      | Accepted FCR capacity (MW)                                                |
| `settlement_price_fcr`              | FCR settlement price (EUR/MW per hour)                                    |
| `weighted_capacity_fcr`             | Accepted capacity multiplied by delivery hours within the window          |
| `weighted_settlement_price_fcr`     | Settlement price multiplied by delivery hours within the window           |
| `delivery_hours_fcr`                | FCR delivery hours in the window                                          |
| `capacity_fcr_weighted_avg`         | Capacity-weighted average accepted FCR capacity over the 4-hour EFA block |
| `settlement_price_fcr_weighted_avg` | Capacity-weighted average FCR settlement price over the 4-hour EFA block  |

#### aFRR

Positive and negative energy categories refer to upward and downward aFRR energy activation respectively.

| Category                           | Description                                           |
| ---------------------------------- | ----------------------------------------------------- |
| `revenue_afrr_capacity`            | aFRR capacity revenue                                 |
| `revenue_afrr_energy`              | Combined aFRR energy revenue (positive plus negative) |
| `revenue_afrr_energy_pos`          | aFRR positive (upward) energy revenue                 |
| `revenue_afrr_energy_neg`          | aFRR negative (downward) energy revenue               |
| `settlement_price_afrr_energy_pos` | Settlement price for positive aFRR energy activations |
| `settlement_price_afrr_energy_neg` | Settlement price for negative aFRR energy activations |
| `total_volume_afrr_energy_pos`     | Total activated positive aFRR energy volume           |
| `total_volume_afrr_energy_neg`     | Total activated negative aFRR energy volume           |

#### Tolling and virtual battery auction

| Category               | Description                          |
| ---------------------- | ------------------------------------ |
| `revenue_tolling`      | Tolling revenue                      |
| `annual_price_tolling` | Tolling annual price                 |
| `revenue_vba`          | Virtual battery auction revenue      |
| `hurdle_price_vba`     | Virtual battery auction hurdle price |

#### Normalised revenue (per MW)

Normalised revenue divides absolute revenue (EUR) by the virtual asset's average rated power capacity (MW), where capacity is the mean of rated charge and discharge power. This allows comparison across assets of different sizes.

| Category                             | Description                                       |
| ------------------------------------ | ------------------------------------------------- |
| `revenue_normalised_total`           | Total revenue normalised per MW                   |
| `revenue_normalised_wholesale`       | Wholesale revenue normalised per MW               |
| `revenue_normalised_fcr`             | FCR revenue normalised per MW                     |
| `revenue_normalised_afrr_capacity`   | aFRR capacity revenue normalised per MW           |
| `revenue_normalised_afrr_energy`     | Combined aFRR energy revenue normalised per MW    |
| `revenue_normalised_afrr_energy_pos` | Positive aFRR energy revenue normalised per MW    |
| `revenue_normalised_afrr_energy_neg` | Negative aFRR energy revenue normalised per MW    |
| `revenue_normalised_vba`             | Virtual battery auction revenue normalised per MW |
| `revenue_normalised_tolling`         | Tolling revenue normalised per MW                 |

#### Normalised revenue (per MW per year)

These categories scale the per-MW normalised values by 365 to express an annualised rate (EUR/MW/year).

| Category                                      | Description                                                |
| --------------------------------------------- | ---------------------------------------------------------- |
| `revenue_normalised_per_year_total`           | Total normalised revenue per MW per year                   |
| `revenue_normalised_per_year_wholesale`       | Wholesale revenue normalised per MW per year               |
| `revenue_normalised_per_year_fcr`             | FCR revenue normalised per MW per year                     |
| `revenue_normalised_per_year_afrr_capacity`   | aFRR capacity revenue normalised per MW per year           |
| `revenue_normalised_per_year_afrr_energy`     | Combined aFRR energy revenue normalised per MW per year    |
| `revenue_normalised_per_year_afrr_energy_pos` | Positive aFRR energy revenue normalised per MW per year    |
| `revenue_normalised_per_year_afrr_energy_neg` | Negative aFRR energy revenue normalised per MW per year    |
| `revenue_normalised_per_year_vba`             | Virtual battery auction revenue normalised per MW per year |
| `revenue_normalised_per_year_tolling`         | Tolling revenue normalised per MW per year                 |

***

## Physical Assets

This API manages physical assets on the terralayr platform: asset parameters, schedules, ancillary bids and results, metadata, logbook entries, unavailabilities, and EEX notifications.

***

## Asset Monitoring

This API provides timeseries datapoints for physical assets, allowing you to observe asset behaviour and operational state over time.

***

## Authentication

All endpoints require a Bearer token in the `Authorization` header.

**Step 1 — get a token:**

```http theme={null}
POST https://api.trlyr.com/auth/public/authenticate
Content-Type: application/json

{
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
}
```

Extract `access_token` from the response body.

**Step 2 — use the token on every request:**

```http theme={null}
Authorization: Bearer <access_token>
```

Your username and password are set when you accept an invitation to join your organisation. If you need access, contact [support@trlyr.com](mailto:support@trlyr.com).