# Fremby ProAPI Data Service

> The Fremby ProAPI gives you programmatic, read-only access to your fleet's telemetry and daily aggregates — the same data that powers Fremby dashboards and the Microsoft Power BI / Power Flow integrations.

- OpenAPI 3.1.0 specification: https://proapi.fremby.no/swagger/doc.json
- Interactive documentation: https://proapi.fremby.no/
- Base URL: https://proapi.fremby.no/api

## Response formats
Endpoints return JSON or CSV. Where an endpoint supports more than one format, select it
with the `Accept` header:
- `Accept: application/json` → a JSON array of records.
- `Accept: application/stream+json` → the same records as a newline-delimited JSON stream,
friendlier for very large fleets.
- `Accept: text/csv` → a CSV download whose first row is the column header.

Not every endpoint offers every format: some are JSON-only (e.g. the project listings) and
some are CSV-only (e.g. raw equipment telemetry). For endpoints that support CSV, a request
with no `Accept` header returns CSV.

## Authentication
All endpoints require a JWT **Bearer** token: `Authorization: Bearer <token>`.
Tokens are issued per organization. If you authenticate with a *personal* token that
spans more than one organization, also pass the `orgID` query parameter to select which
organization to read. With an organization-scoped token, `orgID` is not needed.

## Identifiers
Object identifiers (`equipmentProfileID`, `projectID`, `locationID`, `shareContractID`, …)
are read from API responses and passed back unchanged.

## Dates, ranges and time zones
All timestamps are **UTC**, formatted as RFC 3339 / ISO 8601. Reports accept a
`rangeStart` and `rangeEnd` (both inclusive); when omitted, default to the last 7 days (project/fleet listings to all history).
Pass `fullRange=true` to ignore the range and return the entire available history.

## Versioning
Endpoints are versioned in the path (`/bi/v1/…` … `/bi/v6/…`). Always prefer the
highest version available for a given report; lower versions are kept for compatibility
and are marked deprecated.

## Errors
A failed request returns the matching 4xx/5xx status with an RFC 7807 problem
body (`application/problem+json`): `{"type": …, "title": …, "status": …, "detail": …}`.

## Endpoints

Current versions only. The specification also lists older versions, marked deprecated.
Parameters, response schemas and examples are in the specification.

### Fleet

Every equipment that has belonged to the fleet, with its current attributes.

- `GET https://proapi.fremby.no/api/bi/v1/fleet/snapshot`: Fleet snapshot (latest values per equipment)
- `GET https://proapi.fremby.no/api/bi/v5/fleet`: Fleet list export

### Telemetry

Raw and per-sample measurement series for individual equipment and metrics.

- `GET https://proapi.fremby.no/api/bi/v1/digitalEquipment/telemetry`
- `GET https://proapi.fremby.no/api/bi/v1/equipment/telemetry`: Equipment telemetry report
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeactiveregenerationhours`: Active regeneration hours (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativedistance`: Distance (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeenergyaccharged`: AC energy charged (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeenergycharged`: Energy charged (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeenergydccharged`: DC energy charged (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeenergyused`: Energy used (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativefuelused`: Fuel used (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeidlehours`: Idle hours (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeloadcount`: Load count (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativenonproductiveidlehours`: Non-productive idle hours (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativeoperatinghours`: Operating hours (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativepayloadtotal`: Payload totals (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/cumulativepowertakeoffhours`: Power-take-off hours (cumulative)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/locations`: Equipment locations

### Daily snapshots

Pre-aggregated daily values (last-24h and cumulative) per equipment, location, project or work site.

- `GET https://proapi.fremby.no/api/bi/v1/location/timeseries/dailylast24snapshot`: Daily last-24h snapshot for a location
- `GET https://proapi.fremby.no/api/bi/v1/location/timeseries/dailysummarizedsnapshot`: Summarized totals per location
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/dailyaverageengineloadfactor`: Average engine load factor (daily)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/dailyfuelused`: Fuel used (daily)
- `GET https://proapi.fremby.no/api/bi/v1/timeseries/dailypeakspeed`: Peak speed (daily)
- `GET https://proapi.fremby.no/api/bi/v2/location/timeseries/dailysnapshot`: Daily snapshot for a location
- `GET https://proapi.fremby.no/api/bi/v5/project/timeseries/equipmentdailysnapshot`: Daily snapshot for a project's equipment
- `GET https://proapi.fremby.no/api/bi/v5/projects/timeseries/dailysnapshot`: Daily snapshot across projects
- `GET https://proapi.fremby.no/api/bi/v5/share-contract/timeseries/dailysnapshot`: Daily snapshot for a share contract
- `GET https://proapi.fremby.no/api/bi/v5/work-site/timeseries/dailysnapshot`: Daily snapshot for a work site
- `GET https://proapi.fremby.no/api/bi/v6/timeseries/dailysnapshot`: Daily snapshot (active fleet)

### Projects

Project listings and project-scoped equipment reports.

- `GET https://proapi.fremby.no/api/v1/project/fleet`: Equipment in a project
- `GET https://proapi.fremby.no/api/v3/projects`: List organization projects