Business Validity API¶

Base path: /core/api/communities/{community_id}/business-validity

These endpoints let you inspect and move whole community structures through time: list the dated versions (revisions) of every versioned entity, read the structure effective on a given day, export and import a community's full history, and delete one exact wrong version. Creating and updating versions is not done here: it is done with the regular entity endpoints (communities, members, meters, resources, ownerships, contracts, RESP, bilateral prices, EMS), which all take start_date / end_date. See Business Validity concepts for the model behind these endpoints.

How versioning works in this API¶

Term	Meaning
`start_date`	First day (inclusive) a version applies. Europe/Lisbon calendar day, no time of day
`end_date`	Last day (inclusive) a version applies. `null` means open-ended
`effective_at`	The day you want to read the structure for. A version is effective when `start_date <= effective_at` and (`end_date` is `null` or `end_date >= effective_at`)
Version `id`	Identifies one revision of a stable entity. In the responses of this page it is returned as `id` (not `version_id`). Use it as `{version_id}` in the exact-version delete
Stable identity	The entity itself (`meter_id`, `resource_id`, `resp_id`, `user_id`...), which never changes between versions
Gap	A day with no effective version for an entity. The entity is ignored on that day
`context_hash`	SHA-256 of every version effective on one day (see Structure snapshot). Two days with the same hash can be processed in one market or settlement run

There is no separate preview, impact or timeline endpoint

The "timeline" of an entity is the list returned by its /versions endpoint, ordered by start_date. To see the structure on a given day use GET /snapshot or the effective_at parameter of the regular endpoints. Writes are applied directly (there is no dry-run): any write that touches past dates invalidates the market sessions in the affected period (see Side effects).

Side effects on sessions¶

Writes that change history (POST /import and DELETE /managed/..., as well as the dated writes of the regular entity endpoints) call the same invalidation routine for the affected Lisbon-local date range (start_date 00:00 to end_date 23:59, or without upper bound when end_date is null). For every market session in that range:

the status is set back to OPEN and market_context_hash is cleared;
transactions, offers, bilateral energy allocations and every settlement output are deleted;
opportunity costs that were calculated (not uploaded) are deleted;
uploaded measurements and uploaded opportunity costs are kept.

Run market clearing and settlement again for those days. See Market.

Access control¶

All endpoints share the router-level dependencies: the community must exist (404 otherwise), the caller must be authenticated and verified, and the generic community permission check applies:

Platform admin (SUPER_USER): everything.
Community admin: everything in their community.
Community member: GET endpoints only (this includes /export, which contains member personal data). POST and DELETE return 403.
Non-member: 403.
Own membership timeline: any authenticated, verified user may GET their own /memberships/{user_id}/versions (where user_id is the caller) even after they left the community.

Access is always based on current permissions, never on the date queried.

Endpoint summary¶

Method	Path	Purpose
GET	`/core/api/communities/{community_id}/business-validity/export`	Export a snapshot or the history of the whole community structure
POST	`/core/api/communities/{community_id}/business-validity/import`	Replace the community history from an export (or a legacy 1.0.14 file)
GET	`/core/api/communities/{community_id}/business-validity/snapshot`	Structure effective on one day, with a deterministic `context_hash`
GET	`/core/api/communities/{community_id}/business-validity/config/versions`	Community configuration versions
GET	`/core/api/communities/{community_id}/business-validity/memberships/{user_id}/versions`	Membership status and role timeline of a member
GET	`/core/api/communities/{community_id}/business-validity/meters/{meter_id}/versions`	Meter versions
GET	`/core/api/communities/{community_id}/business-validity/resources/{resource_id}/versions`	Resource versions with type-specific `details`
GET	`/core/api/communities/{community_id}/business-validity/ownerships/{resource_id}/{user_id}/versions`	Ownership share history of a member on a resource
GET	`/core/api/communities/{community_id}/business-validity/meters/{meter_id}/contracts/versions`	Every contract of a meter
GET	`/core/api/communities/{community_id}/business-validity/resp/{resp_id}/versions`	RESP versions of a CPE pair
GET	`/core/api/communities/{community_id}/business-validity/fixed-bilateral/{receiver_user_id}/{provider_user_id}/versions`	Fixed bilateral price history
GET	`/core/api/communities/{community_id}/business-validity/ems/{config_id}/versions`	EMS configuration versions
DELETE	`/core/api/communities/{community_id}/business-validity/managed/{entity_type}/{entity_id}/versions/{version_id}`	Delete one exact version, leaving a gap

Structure snapshot¶

Get Structure Snapshot¶

GET /core/api/communities/{community_id}/business-validity/snapshot

Returns the operation context of the community on one day: the exact version of every versioned record that market, settlement and EMS would use on that day, plus a deterministic hash of that set. Use it to check which versions apply on a day, or to compare two days (equal context_hash means the structure is identical).

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`effective_at`	query	date (`YYYY-MM-DD`)	Yes	Day to resolve (Europe/Lisbon)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/snapshot?effective_at=2026-01-14" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "effective_at": "2026-01-14",
  "context_hash": "9c1185a5c5e9fc54612808977ee8f548b2258d31...",
  "references": [
    {
      "kind": "community_config",
      "identity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version_id": "7d9e1a52-6f0c-4b0b-9a43-0a7b3f2d1c11",
      "start_date": "2026-01-01",
      "end_date": null,
      "payload": { "method_alloc_coeff": "FIXED", "market_rate": "VANILLA_IMR", "lem_trading_fee": 0.01, "status": "ACTIVE" }
    },
    {
      "kind": "resource",
      "identity_id": "b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
      "version_id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
      "start_date": "2026-01-14",
      "end_date": null,
      "payload": { "meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "name": "Battery", "status": "ACTIVE", "detail": { "max_power": 10.0 } }
    }
  ]
}

Tip

references is sorted by (kind, identity_id, version_id). Possible kind values: community_config, membership, meter, resource, ownership, contract, resp, fixed_bilateral_price, ems_configuration.
identity_id is the stable ID (for membership it is the membership ID, not the user_id; for ownership it is {user_id}:{resource_id}). For contract, version_id equals the contract ID, because each contract row is one period.
Only operational versions are listed: resources without a meter (view-only) and ownerships of such resources are omitted. Name, identifier and contact details of the community or members are not versioned and are not included.
context_hash is a SHA-256 of the community ID and all references (including version_id, start_date and end_date). It does not contain effective_at. Market and settlement use it to split runs into context windows (see Effect on operations).
404 when no community configuration version is effective on that day (No community configuration is effective on <date>). 422 if effective_at is missing or not a valid date.

Export and import¶

Export Community Structure¶

GET /core/api/communities/{community_id}/business-validity/export

Exports the community structure in one transactionally consistent read (REPEATABLE READ). Use mode=snapshot to get the versions effective on one day, or mode=history to get every version (optionally restricted to a period). The output can be restored with POST /import.

Auth / permissions: any member of the community, community admin or platform admin. The export contains member personal data (name, email, phone, address, NIF).

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`mode`	query	string	No	`snapshot` (default) or `history`. Any other value returns `422`
`effective_at`	query	date	Required when `mode=snapshot`	Day to export. Ignored in `history` mode
`start_date`	query	date	No	`history` mode: only versions overlapping `[start_date, end_date]`. Ignored in `snapshot` mode
`end_date`	query	date	No	`history` mode: inclusive upper bound. Requires `start_date`

Example

SnapshotHistory

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/export?mode=snapshot&effective_at=2026-01-14" \
  -H "Authorization: Bearer $TOKEN" -o community-2026-01-14.json

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/export?mode=history&start_date=2026-01-01&end_date=2026-06-30" \
  -H "Authorization: Bearer $TOKEN" -o community-history.json

Response (abridged)

{
  "metadata": {
    "schema_version": "2.0.0",
    "timezone": "Europe/Lisbon",
    "public_end_date": "inclusive",
    "mode": "history",
    "effective_at": null,
    "start_date": "2026-01-01",
    "end_date": "2026-06-30"
  },
  "community": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "REC Matosinhos", "identifier": "rec-matosinhos", "phone": "+351 220 000 000", "address": "Rua do Porto 123", "nif": "500000000" },
  "community_config_versions": [ { "id": "7d9e1a52-...", "community_id": "3fa85f64-...", "method_alloc_coeff": "FIXED", "start_date": "2026-01-01", "end_date": null } ],
  "memberships": [ { "id": "c1...", "user_ref": "9b2...", "user": { "id": "9b2...", "name": "Ana Silva", "email": "ana@example.com", "phone": null, "address": null, "nif": null } } ],
  "membership_versions": [],
  "meters": [ { "id": "5a6b7c8d-...", "identifier": "PT0002000000000000000000001234", "type": "CPE" } ],
  "meter_versions": [],
  "resources": [ { "id": "b2c4e6a8-...", "type": "STORAGE" } ],
  "resource_versions": [],
  "resource_detail_versions": { "resource_storage_versions": [], "resource_scpu_versions": [] },
  "ownership_versions": [],
  "contracts": [],
  "contract_tariff_details": { "contract_fixed_tariffs": [], "contract_koefficients": [], "contract_indexed_simplified": [] },
  "resp": [],
  "resp_versions": [],
  "fixed_bilateral_relationships": [],
  "fixed_bilateral_versions": [],
  "ems_configurations": [],
  "ems_configuration_versions": []
}

Tip

snapshot returns only versions effective on effective_at (a gap means the entity has no row in the version lists). history without dates returns all versions; with start_date it returns those overlapping the period (end_date omitted means open-ended).
Stable rows (memberships, meters, resources, resp, fixed_bilateral_relationships, ems_configurations) are always exported in full, regardless of mode or dates.
contracts rows carry the period start in a column named validity (the legacy physical name of start_date), together with end_date. This differs from GET /meters/{meter_id}/contracts/versions, which returns start_date. Keep the file unchanged if you plan to import it.
resource_detail_versions and contract_tariff_details are keyed by database table name (for example resource_storage_versions).
Validation (422): mode=snapshot without effective_at; end_date without start_date in history mode; end_date before start_date.
Dates are inclusive and in Europe/Lisbon, as declared in metadata.

Import Community History¶

POST /core/api/communities/{community_id}/business-validity/import

Restores a community's versioned history from an export file in one atomic transaction. It replaces all existing version rows of the community, so use it to restore or migrate structures, not to append changes. The stable entities (community, users, meters, resources, memberships, RESP pairs, bilateral relationships, EMS configurations) must already exist; the import only rebuilds their versions and contracts.

Auth / permissions: community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID. Must match `community.id` in the file
`legacy_base_effective_date`	query	date	Required for legacy files	Only for legacy files (`"import_version": "1.0.14"`): becomes the `start_date` of every imported record
body	body	object	Yes	A file produced by `GET /export` (`metadata.schema_version` = `2.0.0`), or a legacy 1.0.14 simulator file. See below

Key body fields (schema 2.0.0): metadata (schema_version, timezone, public_end_date), community.id, community_config_versions, membership_versions, meter_versions, resource_versions, resource_detail_versions, ownership_versions, contracts, contract_tariff_details, resp_versions, fixed_bilateral_versions, ems_configuration_versions. Each version row carries its own id, start_date and end_date.

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @community-history.json

Legacy file (needs the base date):

curl -X POST "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/import?legacy_base_effective_date=2026-01-01" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @legacy-community-1.0.14.json

Response

{
  "message": "Business-valid history imported atomically",
  "schema_version": "2.0.0",
  "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Destructive and retroactive

Before inserting, the import deletes all existing versions, contracts (with their tariff details) and resource detail rows of the community. It then invalidates every market session from the earliest start_date in the file onward (no upper bound), deleting their transactions, offers, allocations and settlement outputs (see Side effects). Re-run market and settlement afterwards.

Tip

Errors: 422 for an unsupported schema_version, a timezone other than Europe/Lisbon, public_end_date other than inclusive, unknown stable references (the message lists the IDs), an internal meter whose parent is not a CPE of the community, empty resource names, a legacy file without legacy_base_effective_date, or legacy references that are ambiguous or missing. 409 if the file belongs to another community, if two resources share a name (case-insensitive), or if one CPE/internal meter has resource versions of different resources in overlapping periods.
memberships, meters, resources and other stable lists in the file are only informational: they are not created. Only the version rows are restored. Contract rows must use the validity key for the start date, as in the export.
Legacy 1.0.14 files: every migrated record starts on legacy_base_effective_date and ends on basicInfo.end_date (or is open-ended). Legacy contracts are matched to CPEs by position, so a legacy file needs exactly one contract per CPE or aggregator meter.
Any failure while writing rolls the whole import back. Database-level conflicts that are not pre-validated (for example overlapping periods inside the file) surface as a generic 500 error, and nothing is changed.

Version history¶

All version-list endpoints are read-only, return a JSON array ordered by start_date, are not paginated, and include past, current and future versions. The version row fields are the database columns (id, the stable ID, the versioned fields, start_date, end_date, created_at) plus the extra fields described for each endpoint. For the meaning of each versioned field see the concept pages linked in Business Validity concepts.

List Community Configuration Versions¶

GET /core/api/communities/{community_id}/business-validity/config/versions

Lists every operational configuration version of the community (allocation method, market and settlement parameters, trading fee, EMS type, status and type).

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/config/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "7d9e1a52-6f0c-4b0b-9a43-0a7b3f2d1c11",
    "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "method_alloc_coeff": "FIXED",
    "market_rate": "VANILLA_IMR",
    "market_divisor": 0.5,
    "market_compensation": 0.5,
    "lem_trading_fee": 0.01,
    "settlement_sale_price_type": "INDIVIDUAL",
    "transaction_adjustment_tolerance": 0.001,
    "status": "ACTIVE",
    "type": "CUSTOM",
    "energy_management_type": null,
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z"
  }
]

Tip

Update a configuration with PUT /core/api/communities/{community_id} and start_date (see Communities).
Name, identifier and contact details are not versioned and never appear here.
Returns an empty array when no versions exist. The community itself must exist (404 otherwise).

List Membership Versions¶

GET /core/api/communities/{community_id}/business-validity/memberships/{user_id}/versions

Lists the status and role timeline of one member in the community, including is_host and is_promoter.

Auth / permissions: any member of the community, community admin or platform admin. In addition, a verified user can always read their own timeline (user_id equal to the caller), even after the membership ended.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`user_id`	path	UUID	Yes	The member's user ID (not the membership ID)

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/memberships/9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "membership_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "role_id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a",
    "status": "ACTIVE",
    "is_host": false,
    "is_promoter": false,
    "start_date": "2026-01-01",
    "end_date": "2026-01-30",
    "created_at": "2026-01-01T09:00:00Z",
    "user_id": "9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a",
    "role_name": "MEMBER"
  }
]

Tip

404 (Membership not found) if the user has never been a member of this community.
Ending a membership is done with DELETE /core/api/communities/{community_id}/users/{user_id}?effective_at=...; a dated status: INACTIVE update keeps the member visible but excludes them from operations.
role_name is null if the role record no longer exists.

List Meter Versions¶

GET /core/api/communities/{community_id}/business-validity/meters/{meter_id}/versions

Lists every version of a meter: status, installation_type, production_identifier, ord and parent cpe_id.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`meter_id`	path	UUID	Yes	Stable meter ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/meters/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
    "meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "installation_type": "IC",
    "production_identifier": null,
    "ord": null,
    "cpe_id": null,
    "status": "ACTIVE",
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z",
    "identifier": "PT0002000000000000000000001234",
    "meter_type": "CPE"
  }
]

Tip

identifier and meter_type are the stable fields of the meter, repeated on every row. cpe_id is only set on INTERNAL meters.
404 (Meter not found) if the meter does not belong to this community.
See Meters and Meters and Resources API.

List Resource Versions¶

GET /core/api/communities/{community_id}/business-validity/resources/{resource_id}/versions

Lists every version of a resource, including the type-specific detail (capacity, power, efficiencies...) of that version.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`resource_id`	path	UUID	Yes	Stable resource ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/resources/b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
    "resource_id": "b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
    "meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "name": "Battery",
    "status": "ACTIVE",
    "start_date": "2026-01-01",
    "end_date": "2026-01-13",
    "created_at": "2026-01-01T09:00:00Z",
    "resource_type": "STORAGE",
    "details": {
      "resource_version_id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
      "nominal_capacity": 10.0,
      "max_power": 5.0,
      "charging_efficiency": 0.95,
      "discharging_efficiency": 0.95,
      "min_SOC": 0.1,
      "max_SOC": 0.9,
      "deg_cost": 0.01,
      "init_soc": 0.5
    }
  },
  {
    "id": "1f2a3b4c-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "resource_id": "b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
    "meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "name": "Battery",
    "status": "ACTIVE",
    "start_date": "2026-01-14",
    "end_date": null,
    "resource_type": "STORAGE",
    "details": { "max_power": 10.0 }
  }
]

Tip

meter_id may be null on a version: the resource is then view-only for that period and is excluded from market, settlement, EMS and sizing.
details has the columns of the typed table (IU, IC, SCPU, STORAGE, EV, EWH, HP) and is null if the version has none. Units follow the resource type (kW, kWh). See Resources.
A resource ID that does not exist in the community returns an empty array (no 404).

List Ownership Versions¶

GET /core/api/communities/{community_id}/business-validity/ownerships/{resource_id}/{user_id}/versions

Lists the ownership share (perc_ownership) history of one member on one resource.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`resource_id`	path	UUID	Yes	Stable resource ID
`user_id`	path	UUID	Yes	Owner's user ID

Note the order of the path parameters: resource first, then user.

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/ownerships/b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d/9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
    "user_id": "9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a",
    "resource_id": "b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d",
    "perc_ownership": 50.0,
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z"
  }
]

Tip

Total ownership of a resource may not exceed 100% on any day (checked by the write endpoints, per day). See Resources.
Returns an empty array (not 404) if the pair has no ownership history or the resource is not in the community.
In the exact-version delete, this pair is identified as {resource_id}~{user_id}.

List Contract Versions¶

GET /core/api/communities/{community_id}/business-validity/meters/{meter_id}/contracts/versions

Lists every contract of a meter. Each contract row is itself one period (a meter has at most one contract per day), so the list is the contract history.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`meter_id`	path	UUID	Yes	Stable meter ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/meters/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/contracts/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e",
    "meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "user_id": "9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a",
    "buy_type": "contract_fixed_tariff",
    "sell_type": "indexed_simplified",
    "voltage_level": "BTN",
    "tariff_cycle": "BI_HOURLY",
    "with_holidays": false,
    "contracted_power": 6.9,
    "end_date": "2026-06-30",
    "start_date": "2026-01-01"
  }
]

Tip

The legacy validity column is not returned; use start_date. Tariff details (buy/sell prices) are not included; read them from the contract endpoints (see Contracts).
Contracts are the only entity whose version id equals the contract ID.
Empty array (not 404) when the meter has no contracts or is not in the community.

List RESP Versions¶

GET /core/api/communities/{community_id}/business-validity/resp/{resp_id}/versions

Lists the is_active history of one RESP (public grid) relationship between a provider and a receiver CPE.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`resp_id`	path	UUID	Yes	Stable RESP relationship ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/resp/4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "resp_id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "is_active": true,
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z",
    "provider_meter_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "receiver_meter_id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e"
  }
]

Tip

RESP relationships are never deleted. Set a period with PUT /core/api/communities/{community_id}/resp/{resp_id}?effective_at=YYYY-MM-DD[&end_date=YYYY-MM-DD] and is_active in the body.
404 (RESP relationship not found) if resp_id is not in this community.

List Fixed Bilateral Price Versions¶

GET /core/api/communities/{community_id}/business-validity/fixed-bilateral/{receiver_user_id}/{provider_user_id}/versions

Lists the price history (EUR/kWh) of the fixed bilateral relationship between a receiver and a provider member.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`receiver_user_id`	path	UUID	Yes	User ID of the receiver (buyer)
`provider_user_id`	path	UUID	Yes	User ID of the provider (seller)

Note the order: receiver first, then provider.

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/fixed-bilateral/9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a/8a1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d5e/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "6e7f8a9b-0c1d-4e2f-9a3b-4c5d6e7f8a9b",
    "relationship_id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "price": 0.08,
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z",
    "receiver_user_id": "9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a",
    "provider_user_id": "8a1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d5e"
  }
]

Tip

404 (Bilateral relationship not found) if the pair has no relationship in this community.
Only the fixed price is versioned; per-interval bilateral prices are time series and are not versioned. See Market.
In the exact-version delete, this pair is identified as {receiver_user_id}~{provider_user_id}.

List EMS Configuration Versions¶

GET /core/api/communities/{community_id}/business-validity/ems/{config_id}/versions

Lists the versions of one Energy Management (EMS) configuration: horizon, delta_t, coefficient flags, config_data and is_active.

Auth / permissions: any member of the community, community admin or platform admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`config_id`	path	UUID	Yes	Stable EMS configuration ID

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/ems/8a9b0c1d-2e3f-4a4b-9c5d-6e7f8a9b0c1d/versions \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "9b0c1d2e-3f4a-4b5c-8d6e-7f8a9b0c1d2e",
    "configuration_id": "8a9b0c1d-2e3f-4a4b-9c5d-6e7f8a9b0c1d",
    "horizon": 24,
    "delta_t": 1.0,
    "strict_pos_coeffs": true,
    "total_share_coeffs": false,
    "config_data": {},
    "is_active": true,
    "start_date": "2026-01-01",
    "end_date": null,
    "created_at": "2026-01-01T09:00:00Z",
    "module_type": "OSTEC"
  }
]

Tip

module_type is the stable type of the configuration and is repeated on each row.
404 (EMS configuration not found) if config_id is not in this community.
EMS calculations whose horizon crosses a day on which an EMS configuration or the community structure changes are rejected with 409 (Operation crosses a business-context boundary on YYYY-MM-DD). See Energy Management API.

Delete a version¶

Delete One Exact Version¶

DELETE /core/api/communities/{community_id}/business-validity/managed/{entity_type}/{entity_id}/versions/{version_id}

Permanently deletes one version (revision) of a versioned entity without touching its other versions or its stable identity. The version's inclusive period becomes a gap. Use it to remove a wrong or duplicated revision, not to end an entity (for that use the regular DELETE ...?effective_at= endpoints).

Auth / permissions: community admin or platform admin. Members receive 403.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community ID
`entity_type`	path	string	Yes	`config`, `membership`, `meter`, `resource`, `ownership`, `contract`, `resp`, `fixedBilateral` or `ems`
`entity_id`	path	string	Yes	Stable identity of the entity, in the format of the table below
`version_id`	path	UUID	Yes	The `id` of the version, as returned by the `/versions` endpoints

`entity_type`	`entity_id`	Version taken from
`config`	Ignored (use the community ID); the community's configuration versions are searched	`config/versions`
`membership`	`{user_id}`	`memberships/{user_id}/versions`
`meter`	`{meter_id}`	`meters/{meter_id}/versions`
`resource`	`{resource_id}`	`resources/{resource_id}/versions`
`ownership`	`{resource_id}~{user_id}`	`ownerships/.../versions`
`contract`	`{meter_id}`	`meters/{meter_id}/contracts/versions` (the contract `id`)
`resp`	`{resp_id}`	`resp/{resp_id}/versions`
`fixedBilateral`	`{receiver_user_id}~{provider_user_id}`	`fixed-bilateral/.../versions`
`ems`	`{config_id}`	`ems/{config_id}/versions`

Example

curl -X DELETE "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/business-validity/managed/ownership/b2c4e6a8-1d3f-4a5b-8c7d-9e0f1a2b3c4d~9b2d6c1e-3a4f-4d5e-8f6a-7b8c9d0e1f2a/versions/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "entity_type": "ownership",
  "version_id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
  "start_date": "2026-01-01",
  "end_date": null
}

Retroactive, irreversible, not dependency-checked

The row is deleted (for a resource, together with its typed detail row) and every market session from start_date to end_date (or from start_date onward for open-ended versions) is reopened, with its transactions, offers, allocations and settlement outputs deleted (see Side effects). This endpoint does not run the structural checks of the regular write endpoints (for example, it will not stop you from deleting a resource version that still has ownerships in that period), and it does not trim or merge neighbouring versions.

Tip

Returns 200 with the deleted version summary (not 204).
404 when: the entity or version is not found in this community, the version belongs to a different entity, entity_id is not a UUID (or not two UUIDs joined by ~ for pairs), or entity_type is unknown (Unsupported business-valid entity: <type>).
The stable parents are locked (FOR UPDATE) while the version is deleted, so concurrent writes to the same entity wait.
To end an entity from a day onward without deleting a specific revision, use the regular DELETE endpoints with effective_at (see Ending a period).