Introduction

The rebase.energy platform is a home for the physical assets you operate, the way they relate to each other, and the data that describes them: sites, turbines, panels, batteries, grid zones and the interconnections between them, and the measurements and forecasts attached to each. The API is a small, uniform REST surface over that model. Once you know how the handful of concepts below relate, every endpoint reads the same way.

The mental model

A workspace is the tenancy boundary. Every API key is bound to exactly one workspace, and every record and timeseries you create or read lives in that workspace. There is nothing to pass in requests: the key implies the workspace.

Object types describe the kinds of records a workspace can hold. Two are built in, sites and assets. A workspace defines its own custom object types with their own attribute schemas: metering points, grid zones, interconnections, contracts. GET /objects returns the catalog, and each entry's name is the slug used in every /objects/{object_name} route. The catalog holds types; instances are records.

A record is one envelope plus values, whatever its type. The envelope is the platform's and is the same for every record: id, object (the type slug), name, timestamps, parent_id (set on a part) and stats (numbers the platform computes, such as a site's total_capacity_kw). values is the type's schema and nothing else. Writes use the same two halves. See Objects and records.

An attribute holds either a value or other records. The two attribute types that hold records are object (one) and objects (a list). Each declares a relation:

• part: the far record belongs to this one alone and is deleted with it. A site owns its assets; a plant owns its turbines.
• reference (the default): the far record stays where it is, can be referenced from many places, and cutting the reference never deletes it. A synchronous area references zones; a country references the same zones.

A record can sit between two records. A type with a between attribute holds exactly the two records each of its records runs between: an interconnection between two zones, a cable between two substations. Such a record is the relationship, and it takes attributes, timeseries, and the same routes as anything else. See Linking records.

Timeseries attach to records. Any record can carry named series (power production, prices, forecasts). A series has a type (a slug you choose, such as power-production), a unit, and one of two shapes:

• singleindex: measurements and actuals. One value per valid_time, optionally split into named columns.
• multiindex: versioned data such as forecasts. Each point has a valid_time (when the value is for), a knowledge_time (when the value was known, that is the forecast issue time), and named columns such as q10, q50, q90. Reads resolve to the latest-known value per valid time by default, and you can ask for a specific run or for the state as of a past instant.

Under both shapes the store is append-only. A later upload for the same time becomes the current value without erasing the old one, a deletion is a retraction, and as_of reads show what was known when. That surfaces as three promises: re-uploads are safe, nothing is ever lost, and "what did we know at the time" is always answerable. See Upload / read timeseries.

Two questions that settle most modelling choices

• Does the relationship itself need attributes or a timeseries? Then it is its own object type, with a between attribute holding the two records: an interconnection has capacities and a flow. Otherwise it is a link attribute on one of the two records.
• Does the record on the far end belong to this one alone, and die with it? Then the link's relation is part. Otherwise it is a reference.

Base URL

https://api-v3.rebase.energy/platform/v3

All bodies are JSON. Timestamps are ISO 8601; send an explicit UTC offset, for example 2024-06-01T12:00:00+00:00 or 2024-06-01T12:00:00Z, and expect UTC back.

Where to go next