Skip to content

Communities API

Base path: /core/api/communities

Communities are the top-level entity in RECreation. They represent a Renewable Energy Community (see Renewable Energy Community) with members, meters, and resources. This page covers the community itself: creating, reading, updating and deleting it, its dashboard metrics, its CPE structure, the current user's membership data and the production operations (market clearing and settlement).

A community's operational configuration is dated: start_date (required) and end_date (optional, inclusive) set the period it applies to, and effective_at reads it as it was on another day. See Business Validity.

Member management lives on another page

Adding, listing, updating, inviting and ending members of a community (/core/api/communities/{community_id}/users... and the /members... list, search and KPI routes) are documented in the Auth & Users API page. Only GET /core/api/communities/{community_id}/members/me is on this page.

Permissions and error codes

Every route requires a verified account (otherwise 404 Please verify your account.). Routes without {community_id} in the path are global: reads are open to any verified user, writes are SUPER_USER only. Routes with {community_id} require membership of that community: reads are open to any member (MEMBER or ADMIN) and writes require community ADMIN. SUPER_USER bypasses all checks. Failing these returns 403.

A {community_id} that does not exist also returns 403 (Community with id: ... does not exist.), because the platform's not-found errors use status 403. Duplicate names or identifiers return 409. Validation failures return 422.

Endpoint summary

Method Path Purpose
POST /core/api/communities Create a community (optionally with a full preload)
GET /core/api/communities List the communities the user can access
GET /core/api/communities/by-identifier Look up a community by its identifier
GET /core/api/communities/{community_id} Get a community's configuration as of a day
PUT /core/api/communities/{community_id} Update a community (dated revision)
DELETE /core/api/communities/{community_id} Permanently delete a community and all its data
GET /core/api/communities/{community_id}/community_structure CPE tree with members, meters, resources and owners
GET /core/api/communities/{community_id}/metrics/kpis Community KPIs for a period
GET /core/api/communities/{community_id}/metrics/savings Community savings time series
GET /core/api/communities/{community_id}/metrics/ac_energy Community shared (AC) energy time series
GET /core/api/communities/{community_id}/members/me Current user's data in this community
POST /core/api/communities/{community_id}/operations/run Start market clearing or settlement (async task)
GET /core/api/communities/{community_id}/tasks/{task_id} Poll the status of an async task

Community lifecycle

Create a Community

POST /core/api/communities

Creates a community, makes the calling user its ADMIN, and optionally creates its members, meters, contracts, resources and fixed bilateral prices in the same call (preload). start_date (required) and end_date (optional, inclusive) set the period of the first configuration version.

Auth / permissions: SUPER_USER only (403 Only super-users can perform this action for anyone else).

Parameter In Type Required Description
name body string Yes Community name. Unique, case-insensitive
identifier body string Yes Short unique identifier (non-empty, trimmed, unique case-insensitive)
method_alloc_coeff body enum Yes FIXED, PROPORTIONAL or DYNAMIC. See Allocation methods
start_date body date Yes First day (inclusive, Europe/Lisbon) of the configuration
end_date body date No Last day (inclusive). null = open-ended
type body enum No PROD (default), DEMO, SIMULATION, CUSTOM or TEST
market_rate body enum No VANILLA_IMR, VANILLA_SDR, VANILLA_CV, FIXED_PRICE, BILATERAL_PRICE, TREE_DNAC, FIXED_BILATERAL_PRICE or FIXED_TREE_DNAC. See Market
market_divisor body float No Fraction applied to the market price (server default 0.5)
market_compensation body float No Seller compensation factor (server default 0.5)
market_small_increment body float No Price increment used by the market algorithm (server default 0.1)
market_fixed_price body float No Price for FIXED_PRICE rates (server default 0.0805)
lem_trading_fee body float No Flat fee paid by sellers per LEM transaction (server default 0)
settlement_sale_price_type body string No INDIVIDUAL (default) or AGGREGATED surplus sale price. Free text, not validated by an enum
transaction_adjustment_tolerance body float No Tolerance for adjustment corrections (server default 0.05)
community_or_aggregator_type body enum No EGAC (default), AGGREGATOR or EGAC+AGGREGATOR
phone, address, nif body string No Contact details of the community entity
preload body object No members[], meters[], resources[] and fixed_bilateral_prices[] linked by *_ref strings. See below

Fields omitted (or null) fall back to the server defaults above. status is created as ACTIVE and energy_management_type as NONE; change them later with Update a Community.

Example

curl -X POST https://<host>/core/api/communities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "REC Matosinhos",
    "identifier": "REC-MATOSINHOS",
    "type": "PROD",
    "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",
    "start_date": "2026-01-01"
  }'

import httpx

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

Response 201 Created (abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "REC Matosinhos",
  "identifier": "REC-MATOSINHOS",
  "phone": "+351 220 000 000",
  "address": "Rua do Porto 123",
  "nif": "500000000",
  "method_alloc_coeff": "FIXED",
  "market_rate": "VANILLA_IMR",
  "market_divisor": 0.5,
  "market_compensation": 0.5,
  "market_small_increment": 0.1,
  "market_fixed_price": 0.0805,
  "lem_trading_fee": 0.01,
  "settlement_sale_price_type": "INDIVIDUAL",
  "transaction_adjustment_tolerance": 0.001,
  "energy_management_type": "NONE",
  "community_or_aggregator_type": "EGAC",
  "status": "ACTIVE",
  "type": "PROD",
  "created_at": "2026-01-01T09:00:00+00:00",
  "version_id": null,
  "start_date": null,
  "end_date": null,
  "total_members": 0,
  "resource_types": []
}

Create with a preload (abridged; the complete example is in Creating a Community in One Call)

curl -X POST https://<host>/core/api/communities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Community",
    "identifier": "CommunityACC",
    "method_alloc_coeff": "PROPORTIONAL",
    "market_rate": "FIXED_BILATERAL_PRICE",
    "start_date": "2026-01-01",
    "preload": {
      "members": [
        {"ref": "AnchorRef", "name": "Anchor", "is_host": true, "start_date": "2026-01-01"},
        {"ref": "OffTakerRef", "name": "OffTaker", "start_date": "2026-01-01"}
      ],
      "meters": [
        {"ref": "CPEAnchorRef", "identifier": "PT0002000000000000000000001234",
         "type": "CPE", "installation_type": "IAC", "start_date": "2026-01-01"}
      ],
      "fixed_bilateral_prices": [
        {"provider_ref": "AnchorRef", "receiver_ref": "OffTakerRef",
         "price": 0.1, "start_date": "2026-01-01"}
      ]
    }
  }'

Tip

  • The calling SUPER_USER is added to the new community as ADMIN with the same start_date / end_date. total_members counts only users with the MEMBER role, so a new community returns 0 until members are added.
  • version_id, start_date and end_date are null in this response. They are only filled by Get a Community.
  • A duplicate name or identifier (case-insensitive) returns 409.
  • Side effects: a community folder is created in storage and a per-community log file (logs/logs_community_{id}.log) is started.
  • preload order: members, then non-internal meters, then internal meters (they need cpe_ref), then resources with their ownerships, then contracts (embedded in each CPE meter as contracts[]), then fixed bilateral prices (static price in EUR/kWh). Refs that cannot be resolved (cpe_ref, meter_ref, member_ref, provider_ref, receiver_ref) return 400. *_ref values are discarded after the call; use the returned UUIDs afterwards.
  • The community is committed before the preload runs, so a preload error can leave the community created with only part of its entities. Fix the problem and add the rest through the regular endpoints, or delete the community and retry.
  • A preloaded member with has_dashboard_access: true and an email gets a Keycloak account and an invitation email, as in the regular member creation.
  • Every dated entity in the preload needs its own start_date (contracts still accept the legacy alias validity). nif is not validated on create, but it is on update.

Update a Community

PUT /core/api/communities/{community_id}

Updates the community. start_date is required (and end_date optional): configuration fields change only for that period and the history outside it is kept. Fields you leave out are copied from the version effective on start_date. See Updating (dated revisions).

Auth / permissions: community ADMIN of {community_id} or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community to update
start_date body date Yes First day (inclusive, Europe/Lisbon) of the revision
end_date body date No Last day (inclusive). Omit or null to change everything from start_date on
name, identifier, phone, address, nif body string No Not dated: applied immediately and always show the current value
method_alloc_coeff body enum No Dated. FIXED, PROPORTIONAL, DYNAMIC
market_rate, market_divisor, market_compensation, market_small_increment, market_fixed_price, lem_trading_fee body enum / float No Dated market parameters
settlement_sale_price_type, transaction_adjustment_tolerance body string / float No Dated settlement parameters
energy_management_type body enum No Dated. NONE, GDBN_FLEXIBILITY, OSTEC_FLEXIBILITY, OSTEC_SIMPLE, RENEWING, CAPWATT, HEDGE_IOT
community_or_aggregator_type body enum No Dated. EGAC, AGGREGATOR, EGAC+AGGREGATOR
status body enum No Dated. ACTIVE, INACTIVE, DELETED
type body enum No Dated. PROD, DEMO, SIMULATION, CUSTOM, TEST

Example

curl -X PUT https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "market_rate": "VANILLA_SDR",
    "lem_trading_fee": 0.02,
    "start_date": "2026-03-01",
    "end_date": null
  }'

Response 200 OK (abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "REC Matosinhos",
  "identifier": "REC-MATOSINHOS",
  "method_alloc_coeff": "FIXED",
  "market_rate": "VANILLA_SDR",
  "lem_trading_fee": 0.02,
  "status": "ACTIVE",
  "type": "PROD",
  "version_id": null,
  "start_date": null,
  "end_date": null,
  "total_members": null,
  "resource_types": null
}

Retroactive changes reopen sessions

If the request changes any dated field, every market session inside [start_date, end_date] goes back to OPEN and its transactions, offers, allocations and settlement outputs are deleted (uploaded measurements and uploaded opportunity costs are kept). Run market clearing and settlement again for those dates. Sending only name, identifier, phone, address or nif does not reopen anything.

Tip

  • Only fields present in the body are changed (exclude_unset). start_date is still required even when you only change name or phone.
  • name and identifier must stay unique (case-insensitive): a clash with another community returns 409. identifier, if sent, cannot be null or blank (422).
  • nif, if sent, is validated as a Portuguese NIF (9 digits, not starting with 0, valid check digit; spaces are ignored), otherwise 422. An empty string is stored as null.
  • Keep end_date on or after start_date. The schema does not check it, and a dated change with end_date before start_date fails with a server error (500).
  • The response is the stored community row. It does not include total_members, resource_types or the version fields; read the effective values with Get a Community and effective_at.

Delete a Community

DELETE /core/api/communities/{community_id}

Permanently deletes a community and all of its data: meters, resources, contracts, loads, sessions, market and settlement outputs, business-validity history, memberships and its files on disk. This cannot be undone.

Auth / permissions: community ADMIN of {community_id} or SUPER_USER (the route only requires write access to the community; there is no extra SUPER_USER-only check).

Parameter In Type Required Description
community_id path UUID Yes Community to delete

Example

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

Response 204 No Content (empty body)

Warning

The delete is irreversible and, unlike ending a member, meter or resource, it does not keep any business-validity history. The community's storage folder and log file are removed after the database delete succeeds. User accounts are not deleted by this endpoint.

Tip

  • Everything is removed in one database transaction. If a remaining foreign key blocks the delete, nothing is removed and the call returns 409 with Community could not be deleted: ....
  • After the last community is deleted, GET /core/api/communities returns [] for a SUPER_USER.

Reading communities

List Communities

GET /core/api/communities

Returns the communities the authenticated user can access: every community for a SUPER_USER, otherwise the communities where the user has an ACTIVE membership today (Europe/Lisbon).

Auth / permissions: any verified user. No parameters.

Example

curl https://<host>/core/api/communities \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "REC Matosinhos",
    "identifier": "REC-MATOSINHOS",
    "method_alloc_coeff": "FIXED",
    "market_rate": "VANILLA_IMR",
    "energy_management_type": "NONE",
    "status": "ACTIVE",
    "type": "PROD",
    "created_at": "2026-01-01T09:00:00+00:00",
    "version_id": null,
    "start_date": null,
    "end_date": null,
    "total_members": 12,
    "resource_types": ["SCPU", "IC", "STORAGE"]
  }
]

Tip

  • total_members counts users with the MEMBER role whose membership is ACTIVE today; ADMINs are not counted.
  • resource_types is the (unordered) set of resource types in the community.
  • The list returns the stored community row and leaves version_id, start_date and end_date as null. Use Get a Community for the version effective on a given day.

Get a Community by Identifier

GET /core/api/communities/by-identifier?identifier=REC-MATOSINHOS

Looks up one community by its identifier (case-insensitive) and returns its configuration as of a day.

Auth / permissions: any verified user. The route has no {community_id}, so it does not check membership.

Parameter In Type Required Description
identifier query string Yes Community identifier
effective_at query date No Day to read the configuration for (default: today, Europe/Lisbon)

Example

curl "https://<host>/core/api/communities/by-identifier?identifier=REC-MATOSINHOS&effective_at=2026-02-01" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "REC Matosinhos",
  "identifier": "REC-MATOSINHOS",
  "method_alloc_coeff": "FIXED",
  "market_rate": "VANILLA_IMR",
  "status": "ACTIVE",
  "type": "PROD",
  "version_id": null,
  "start_date": null,
  "end_date": null,
  "total_members": 12,
  "resource_types": null
}

Tip

  • Returns 404 Community not found when no community has that identifier. If a community exists but has no configuration for effective_at, the call returns 403.
  • The configuration fields are those effective on effective_at, but this route does not return version_id, start_date, end_date or resource_types. Use the next endpoint when you need them.

Get a Community

GET /core/api/communities/{community_id}

Returns one community with the configuration that applied on effective_at, including the version_id, start_date and end_date of that configuration version.

Auth / permissions: any member of the community (MEMBER or ADMIN) or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID
effective_at query date No Return the configuration valid on this day (default: today, Europe/Lisbon)

Example

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

Response (abridged)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "REC Matosinhos",
  "identifier": "REC-MATOSINHOS",
  "method_alloc_coeff": "FIXED",
  "market_rate": "VANILLA_IMR",
  "market_divisor": 0.5,
  "lem_trading_fee": 0.01,
  "energy_management_type": "NONE",
  "status": "ACTIVE",
  "type": "PROD",
  "version_id": "9b2e6c1a-0d4f-4c5e-8a7b-2f1e3d4c5b6a",
  "start_date": "2026-01-01",
  "end_date": null,
  "total_members": null,
  "resource_types": null
}

Tip

  • The dated fields come from the version effective on effective_at; name, identifier, phone, address and NIF always show their current value.
  • total_members and resource_types are null here. They are filled by List Communities and Get a Community by Identifier (total_members only), and the aggregated numbers by Get Community KPIs.
  • If no configuration version covers effective_at (for example a day before the first start_date), the call returns 403 with Community configuration with effective_date: ... does not exist.

Get Community Structure

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

Returns the CPE tree as it was on effective_at: each CPE with its responsible member and contract, its internal meters, and the resource and owners behind each meter. It feeds the structure graph of the dashboard. See Valid and invalid CPE structures.

Auth / permissions: any member of the community or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID
effective_at query date No Structure valid on this day (default: today, Europe/Lisbon)

Example

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

Response (abridged)

{
  "cpes": [
    {
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "meter_identifier": "PT0002000000000000000000001234",
      "current_contract_id": "0b3c2a8e-6f4d-4a39-9b1e-5d7c8f9a1b2c",
      "current_responsible_member_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "current_responsible_member": "João Silva",
      "internal_meters": [
        {
          "meter_identifier": "PT0002000000000000000000001234-PV",
          "resource": {
            "resource_id": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
            "resource_name": "Rooftop PV",
            "owners": [
              { "owner_id": "d290f1ee-6c54-4b01-90e6-d701748f0851", "owner_name": "João Silva", "owner_perc": 100.0 }
            ]
          }
        }
      ],
      "resource": null
    }
  ]
}

Tip

  • Only ACTIVE CPEs, internal meters and resources effective on effective_at are included; the contract is the one whose period covers that day.
  • A CPE has either internal_meters (and resource: null) or a direct resource (and internal_meters: null). cpes is null when the community has no active CPE.
  • There are no gap errors: a day with no structure simply returns an empty tree.

Dashboard metrics

The three metrics endpoints read settlement outputs. They return data only for sessions that have already been settled (see Settlement). Money is in EUR and energy in kWh, per 15-minute interval before aggregation.

Get Community KPIs

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

Returns community-level KPIs for a period, from settlement outputs plus current counts.

Auth / permissions: any member of the community or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID
start_date query date Yes First day of the period (inclusive)
end_date query date Yes Last day of the period (inclusive, the whole day is included)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/metrics/kpis?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "savings": 412.37,
  "self_sufficiency": 38.5,
  "co2_emissions_reduction": 0,
  "injected_ac_energy": 71.2,
  "injected_energy": 5230.8,
  "total_members": 12,
  "total_resources": 9,
  "total_meters": 14,
  "last_session": "2026-01-31T23:45:00+00:00"
}

Tip

  • savings (EUR) = sum of members' rev_total minus rev_total_no_csc over the period.
  • self_sufficiency (%) = sum of CPE e_slc / sum of CPE e_con, over the intervals where e_slc > 0. injected_ac_energy (%) = sum of |e_slc| / sum of e_inj, over the intervals where e_slc < 0. Both are 0 when no interval matches.
  • injected_energy (kWh) is the sum of the REC-level e_inj.
  • co2_emissions_reduction is always 0 (not computed yet).
  • total_members (role MEMBER, active today), total_resources, total_meters and last_session (timestamp of the most recent session, any status) are not limited to the period.
  • Missing start_date or end_date returns 422.

Get Community Savings

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

Returns the community's savings (EUR) as a time series, aggregated by granularity.

Auth / permissions: any member of the community or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID
start_date query date Yes First day (inclusive)
end_date query date Yes Last day (inclusive)
granularity query enum Yes MIN15, HOUR, DAY, MONTH or YEAR

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/metrics/savings?start_date=2026-01-01&end_date=2026-03-31&granularity=MONTH" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "datetime_timestamp": "2026-01-01T00:00:00+00:00", "savings": 412.37 },
  { "datetime_timestamp": "2026-02-01T00:00:00+00:00", "savings": 389.10 }
]

Tip

  • Savings per interval are rev_total - rev_total_no_csc, summed over all members and over each granularity bucket. A positive value means the community saves money by being a REC.
  • Each item is the start of its bucket in Europe/Lisbon time (with the UTC offset), in ascending order. MONTH buckets start on the 1st and YEAR buckets on January 1.
  • Returns [] when there is no settlement data in the period.
  • The documented granularity values here are the ones the code accepts; other spellings (for example HOURLY) return 422.

Get Community AC Energy

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

Returns the energy shared inside the community (REC-level e_slc, kWh) as a time series, aggregated by granularity.

Auth / permissions: any member of the community or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID
start_date query date Yes First day (inclusive)
end_date query date Yes Last day (inclusive)
granularity query enum Yes MIN15, HOUR, DAY, MONTH or YEAR

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/metrics/ac_energy?start_date=2026-01-01&end_date=2026-01-07&granularity=DAY" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "datetime_timestamp": "2026-01-01T00:00:00+00:00", "energy": 182.4 },
  { "datetime_timestamp": "2026-01-02T00:00:00+00:00", "energy": 201.9 }
]

Tip

  • Values are summed per bucket; timestamps and ordering follow the same rules as Get Community Savings.
  • Returns [] when there is no settlement data in the period.

Current user

Get My Member Data

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

Returns the authenticated user's own record in this community, including their membership status, is_host and is_promoter. Use it after login to know what the current user is in the selected community.

Auth / permissions: any member of the community (MEMBER, ADMIN) or SUPER_USER.

Parameter In Type Required Description
community_id path UUID Yes Community ID

Example

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

Response (abridged)

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "João Silva",
  "email": "joao.silva@example.com",
  "phone": "912345678",
  "address": "Rua das Flores 1, Porto",
  "nif": "123456789",
  "is_verified": true,
  "role": { "id": "5e1c7a0b-3d2f-4b6a-8c9d-0e1f2a3b4c5d", "name": "MEMBER" },
  "created_at": "2026-01-01T09:00:00+00:00",
  "ownerships": [],
  "permissions": [],
  "has_dashboard_access": true,
  "managed_communities": [],
  "status": "ACTIVE",
  "is_host": false,
  "is_promoter": false
}

Tip

  • For a SUPER_USER the user's own data is returned without status, is_host or is_promoter (they are null), and no membership is required.
  • For everyone else, a user who does not belong to the community gets 403 You are not a member of this community.
  • role is the user's platform role, not the community role. The dated membership fields (membership_version_id, start_date, end_date) are not filled by this endpoint; see Members.

Operations

Run an Operation

POST /core/api/communities/{community_id}/operations/run?phase=FIRST_PHASE

Starts a production operation for the community as an asynchronous Celery task and returns a task_id to poll with Get Task Status. clear_market runs market clearing and run_settlement runs settlement for the community's pending sessions. See the sessions and market and settlement API pages for how these steps are normally chained.

Auth / permissions: community ADMIN of {community_id} or SUPER_USER (it is a POST). MEMBER gets 403.

Parameter In Type Required Description
community_id path UUID Yes Community ID
phase query enum Yes FIRST_PHASE (DSO sends proportional allocation first; dynamic allocation is generated) or SECOND_PHASE (DSO allocations are respected). Used by clear_market
task_name body enum Yes clear_market or run_settlement (lowercase)

Example

curl -X POST "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/operations/run?phase=FIRST_PHASE" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "task_name": "clear_market" }'

Response 200 OK

{
  "message": "Processing started",
  "task_id": "c1f3a0de-8b7a-4f1e-9e0a-2b6d5c4a3f21"
}

Tip

  • phase is required even for run_settlement, which ignores it.
  • The endpoint is not available for DEMO communities: it returns 403 Operations endpoint is not available for DEMO communities.
  • A task_name other than the two values above is rejected with 422.
  • The call returns immediately; failures are reported by the task status, not by this response. Run clear_market first and run_settlement once clearing has succeeded.
  • Changes to a community's dated structure reopen the affected sessions, so re-run both steps after a retroactive edit.

Get Task Status

GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false

Returns the state of an asynchronous task started by Run an Operation. Poll it until state is SUCCESS or FAILURE.

Auth / permissions: any member of the community or SUPER_USER. The task itself is not checked against the community.

Parameter In Type Required Description
community_id path UUID Yes Community ID
task_id path string Yes Celery task ID (or group ID) returned when the task was started
group_task query string Yes true if task_id is a Celery group ID. Any other value is treated as false

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/tasks/c1f3a0de-8b7a-4f1e-9e0a-2b6d5c4a3f21?group_task=false" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "state": "SUCCESS",
  "error": null,
  "message": "Clear Market Complete"
}

Tip

  • state is one of PENDING, STARTED, RETRY, FAILURE, SUCCESS or REVOKED. On FAILURE, error holds the task's error message; on SUCCESS, message holds its result (Clear Market Complete, Settlement Complete).
  • Celery reports PENDING for unknown IDs too, so a mistyped task_id looks like a task that has not started yet.
  • With group_task=true the state is only PENDING, SUCCESS (Group task successful) or FAILURE (Group task failed). An unknown group ID is not handled and fails with a server error (500).
  • group_task has no default: omitting it returns 422.