Skip to content

Communities API

Base path: /core/api/communities

Communities are the top-level entity in RECreation. They represent a Renewable Energy Community with members, meters, and resources.

Create a Community

curl -X POST https://<host>/core/api/communities \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "REC Matosinhos",
    "phone": "+351 220 000 000",
    "address": "Rua do Porto 123",
    "nif": "500000000",
    "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,
    "method_alloc_coeff": "FIXED"
  }'

import httpx

response = httpx.post(
    "https://<host>/core/api/communities",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "REC Matosinhos",
        "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,
        "method_alloc_coeff": "FIXED",
    },
)
community = response.json()

List Communities

GET /core/api/communities

Returns all communities the authenticated user belongs to.

Get Community Details

GET /core/api/communities/{community_id}

Returns community details including aggregated metrics (total AC energy, savings, member structure).

Get Community KPIs

GET /core/api/communities/{community_id}/metrics

Returns community-level KPI metrics.

Members

Add Member to Community

POST /core/api/communities/{community_id}/users

Creates a new user and adds them to the community. If has_dashboard_access is true and an email is provided, a Keycloak account is created and an invitation email is sent.

Request body:

{
  "name": "João Silva",
  "email": "joao.silva@example.com",
  "phone": "912345678",
  "nif": "123456789",
  "address": "Rua das Flores 1, Porto",
  "role": "MEMBER",
  "has_dashboard_access": true,
  "is_host": false,
  "is_promoter": false
}
Field Type Required Description
name string ✓ Full name of the member
status string ✓ ACTIVE or INACTIVE — whether the member should be included in market and settlement processes
email string — Email address. Required to grant Dashboard access
phone string — Phone number
nif string — Tax identification number (9 digits)
address string — Street address
role string — MEMBER (default) or ADMIN
has_dashboard_access boolean — If true and email is set, creates a Keycloak account and sends an invite. Default: false
is_host boolean — Designates the member as an Anchor (Host) — a member with priority in the business model, typically responsible for a prosumer CPE that hosts generation assets
is_promoter boolean — Designates the member as a Promoter — an entity that owns production assets and sells energy to the community

Password

The member's initial password is auto-generated. The invited user sets their own password via the Keycloak invitation link sent to their email.

Dashboard access without email

If has_dashboard_access is true but no email is provided, the Keycloak account will not be created. The member will exist in the system but cannot log in to the Dashboard.

curl -X POST https://recreation.inesctec.pt/core/api/communities/{community_id}/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao.silva@example.com",
    "role": "MEMBER",
    "has_dashboard_access": true,
    "is_host": false,
    "is_promoter": false
  }'

import httpx

response = httpx.post(
    f"https://recreation.inesctec.pt/core/api/communities/{community_id}/users",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "João Silva",
        "email": "joao.silva@example.com",
        "role": "MEMBER",
        "has_dashboard_access": True,
        "is_host": False,
        "is_promoter": False,
    },
)
member = response.json()

Response 201 Created:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "João Silva",
  "email": "joao.silva@example.com",
  "phone": "",
  "address": "",
  "nif": "",
  "is_verified": false,
  "role": { "id": "...", "name": "MEMBER" },
  "created_at": "2024-01-15T10:30:00Z",
  "ownerships": [],
  "has_dashboard_access": true,
  "is_host": false,
  "is_promoter": false,
  "permissions": [],
  "managed_communities": []
}

List Community Members

GET /core/api/communities/{community_id}/members

Returns all members of the community with their status and KPI fields.

Query param Type Description
exclude_deleted boolean Exclude deleted members (default: true)