# Docs

- [Relynk Learn](https://learn.relynk.io/docs): Guides and reference for building apps on Relynk building data, with Lovable or your own code.
- Builder API
  - [Get started](https://learn.relynk.io/docs/builder): What you can build with the Relynk Builder API, what you need, and the steps to your first app.
  - [Build an app with Lovable](https://learn.relynk.io/docs/builder/lovable): Connect Lovable to Relynk with a custom connector, share the connection, and build an app on your building data by describing it.
  - Guides
    - [Your first call](https://learn.relynk.io/docs/builder/guides/first-call): Check the connection with GET /me and list your buildings, with curl or JavaScript.
    - [Choose a tenant](https://learn.relynk.io/docs/builder/guides/choose-a-tenant): Let a person who belongs to several Relynk tenants choose one, and pass it on every call.
    - [Rooms and their temperatures](https://learn.relynk.io/docs/builder/guides/rooms-and-temperatures): List the rooms of a building and the latest reading of each room's temperature sensor.
    - [A temperature chart](https://learn.relynk.io/docs/builder/guides/temperature-chart): Hourly average temperatures of a set of sensors over a week, in the shape chart libraries take.
    - [The warmest room last month](https://learn.relynk.io/docs/builder/guides/warmest-room): One summary per sensor over a month, to rank rooms by average or maximum temperature.
    - [A building's energy use](https://learn.relynk.io/docs/builder/guides/building-consumption): Monthly consumption per carrier for a building, with cost and data quality, as the EOS dashboard shows it.
  - Concepts
    - [The data model](https://learn.relynk.io/docs/builder/concepts/data-model): How Relynk describes a building - resources, type keys, points and relationships - in plain language.
    - [Resources and points](https://learn.relynk.io/docs/builder/concepts/resources-and-points): Buildings, levels, rooms, equipment and points, their type keys, and how to find a kind of point on a kind of resource.
    - [Relationships](https://learn.relynk.io/docs/builder/concepts/relationships): How resources are connected - parts, feeds, locations and sub-meters - and how to walk them.
    - [Energy data and data quality](https://learn.relynk.io/docs/builder/concepts/energy-data): EOS consumption of energy, water and waste - meters, carriers, units, confidence and cost coverage.
    - [Time and time zones](https://learn.relynk.io/docs/builder/concepts/time): Oslo time, half-open ranges, date formats, buckets across daylight saving time, and incomplete periods.
    - [Paging and limits](https://learn.relynk.io/docs/builder/concepts/paging-and-limits): How long lists come in pages, and how much one call may ask for.

  - **Reference**
  - [Authentication](https://learn.relynk.io/docs/builder/authentication): OAuth 2.0 user sign-in with PKCE, the audience and scopes, what a caller can see, and choosing a tenant.
  - [Errors and limits](https://learn.relynk.io/docs/builder/errors-and-limits): The error shape, what each status means and what to do, and the limits per call and per caller.
  - [Versioning](https://learn.relynk.io/docs/builder/versioning): Why a function's path never changes its contract, and how new versions are added.
  - API reference
    - [Who the token acts as and the tenants it can read](https://learn.relynk.io/docs/builder/api/me): Who the token acts as and the tenants it can read
    - Buildings
      - [buildings.list (version 1)](https://learn.relynk.io/docs/builder/api/buildings/list-v1): Buildings the user can see in this tenant, ordered by name, or by how well they match search. Page with offset while hasMore is true.
    - Resource types
      - [resourceTypes.list (version 1)](https://learn.relynk.io/docs/builder/api/resource-types/list-v1): The REC/Brick types the tenant actually uses, with how many resources of each type, e.g. to find the type keys of rooms, air handling units or temperature sensors before filtering other functions by them.
      - [resourceTypes.relationships (version 1)](https://learn.relynk.io/docs/builder/api/resource-types/relationships-v1): How types are connected in one building: which relationships exist between which types, and how often. Use it to plan a walk with resources.related, e.g. brick_Has_Part from the building to levels to rooms, or brick_Feeds from an air handling unit to the rooms it serves.
    - Resources
      - [resources.list (version 1)](https://learn.relynk.io/docs/builder/api/resources/list-v1): Resources (buildings, levels, rooms, equipment, points, …) filtered by building, type, name or id. Pages by id: pass nextCursor back until it is null. For the points of equipment or rooms use points.list; for connected resources use resources.related.
      - [resources.related (version 1)](https://learn.relynk.io/docs/builder/api/resources/related-v1): Resources connected to the given ones by one relationship, following it up to maxDepth steps. One row per (fromId, related resource) at its shortest depth. Common relationships: brick_Has_Part (building → levels → rooms; "in" = Is Part Of), brick_Feeds (air handling unit → terminal units → rooms; "in" = Is Fed By), brick_Has_Sub_Meter, brick_Is_Metered_By, rec_Located_In, relynk_Virtual_Meter_Calculated_From. resourceTypes.relationships shows which ones a building uses. For points use points.list with resourceIds.
    - Points
      - [points.list (version 1)](https://learn.relynk.io/docs/builder/api/points/list-v1): Points (sensors, meters, setpoints, commands) with their unit and latest reading, for a building, for given equipment or rooms (resourceIds: the points they have), or by id. Give at least one of buildingId, resourceIds or ids. To find a kind of point on a kind of resource (room temperatures, the supply air temperature of air handling units), first list those resources with resources.list (typeKeys from resourceTypes.list), then pass their ids as resourceIds together with the point typeKeys: a point type with only a buildingId also matches points of every other resource in the building, and typeKeys include subtypes (brick_Temperature_Sensor also matches supply, return and outside air temperature sensors). Each point names its exact typeKey and its resourceIds. Pages by id: pass nextCursor back until it is null. Feed the ids to points.timeseries, points.summary or points.raw.
      - [points.raw (version 1)](https://learn.relynk.io/docs/builder/api/points/raw-v1): Individual readings of up to 20 points over [from, to) (up to 31 days), ordered by point then time. Prefer points.timeseries or points.summary for analysis; use this to inspect exact readings. Pages: pass nextCursor back until it is null. Each page has one series per point that has readings in it, so merge pages by pointId.
      - [points.raw (version 2)](https://learn.relynk.io/docs/builder/api/points/raw-v2): Individual readings of up to 200 points over [from, to) (up to 31 days), ordered by point then time. Prefer points.timeseries or points.summary for analysis; use this to inspect exact readings. Pages: pass nextCursor back until it is null. Each page has one series per point that has readings in it, so merge pages by pointId.
      - [points.summary (version 1)](https://learn.relynk.io/docs/builder/api/points/summary-v1): One summary per point over [from, to) (up to 380 days): count, min and max with their times, average, sum, and first and last reading with their times. Cheaper than points.timeseries when one number per point is enough, e.g. the warmest room last month.
      - [points.timeseries (version 1)](https://learn.relynk.io/docs/builder/api/points/timeseries-v1): Readings of up to 100 points aggregated into Oslo-time buckets over [from, to): one shared time axis t and one array per requested metric per point, null where a bucket has no readings. Days, weeks (Monday) and months start at Oslo midnight, so DST days have 23 or 25 hours. Limits: 15m buckets up to 62 days, others up to 400 days, and points × buckets up to 50 000; split longer ranges into several calls.
      - [points.timeseries (version 2)](https://learn.relynk.io/docs/builder/api/points/timeseries-v2): Readings of up to 1000 points aggregated into Oslo-time buckets over [from, to): one shared time axis t and one array per requested metric per point, null where a bucket has no readings. Days, weeks (Monday) and months start at Oslo midnight, so DST days have 23 or 25 hours. Limits: 15m buckets up to 62 days, others up to 400 days, and points × buckets up to 50 000; split longer ranges into several calls.
    - Meters
      - [meters.list (version 1)](https://learn.relynk.io/docs/builder/api/meters/list-v1): EOS meters (energy, water and waste metering: electricity, district heating and cooling, gas, water, waste) with their carrier, unit, whether they count in building totals (building meters) or are sub-meters, virtual (calculated from other meters) or tenant (lease) meters, what they are used for, and until when EOS has processed them. Filter by building, carrier, id, name, buildingMetersOnly or virtual. Feed the ids to consumption.meters; for a building total use consumption.buildings, which sums exactly the building meters. Pages by id: pass nextCursor back until it is null.
      - [meters.topology (version 1)](https://learn.relynk.io/docs/builder/api/meters/topology-v1): How a building's EOS meters (energy, water, waste) are connected: every meter with its carrier and whether it counts in the building total, the sub-meter tree (parent → child; a parent's consumption includes its children's, and the part no child measures is not sub-metered), what each virtual meter is calculated from with its factor, and overlappingBuildingMeters: virtual building meters fed by another building meter of the same building and carrier, or by its sub-meters, which EOS (like its dashboard) counts both, so the building total includes that consumption twice. Use it to explain a building's metering, to break a total down by sub-meter, and before trusting a building total.
    - Consumption
      - [consumption.buildings (version 1)](https://learn.relynk.io/docs/builder/api/consumption/buildings-v1): Energy, water and waste consumption of buildings from EOS, exactly as the EOS dashboard shows it: per building and carrier (electricity, heating, cooling, gas, water, waste), the sum of the building's building meters (physical and virtual; sub-meters never), per Oslo-time bucket over [from, to), with cost, estimated share, coverage and confidence per bucket and in total. Use this for any building or portfolio consumption, cost or comparison; never add up raw meter points for that. Values are already consumption per hour (not meter readings), in kWh (energy), L (water) or kg (waste); never add different carriers together. null means no data for the bucket, not zero. Omit buildingIds for every building with EOS data. day, week and month buckets need from and to at Oslo midnight; hour buckets up to 62 days, others up to 1100 days, and buildings × carriers × buckets up to 50000.
      - [consumption.meters (version 1)](https://learn.relynk.io/docs/builder/api/consumption/meters-v1): Consumption of up to 10000 EOS meters (energy, water, waste; ids from meters.list) per Oslo-time bucket over [from, to), from the hourly values EOS processed (resets, gaps and virtual meter formulas handled): consumption, the estimated part, cost, missing hours and confidence per bucket, and per meter a total with the peak hour, coverage, cost coverage and hours per confidence tier. Values are consumption per hour, not meter readings: sum them, never take differences. Unit per meter: kWh, L or kg. null means no data, not zero (waste meters: no pickup is 0). For a building's total use consumption.buildings instead of adding meters: sub-meters are part of their parent. from and to must be whole hours; hour buckets up to 62 days, others up to 400, meters × days up to 20000.
  - [For AI agents](https://learn.relynk.io/docs/builder/for-ai-agents): Machine-readable docs for AI coding agents and app builders, on this site and on the API host.