API reference

Virtual segmentation

The segmentation design is versioned: replacing it keeps the current status and bumps the version. Deleting it removes the virtual assets from the fleet.

4 endpoints

GET/v1/assets/{asset_id}/segmentation

Get Segmentation

asset.read

Get the virtual segmentation config of an asset (404 if none exists).

Path parameters

asset_idREQUIRED: string

Example value

curl "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.get(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response200

{
  "asset_id": "<string>",
  "mode": "proportional",
  "status": "draft",
  "version": 0,
  "updated_at": "2026-09-10T13:30:00Z",
  "segments": [
    {
      "segment_id": "<string>",
      "virtual_asset_id": "<string>",
      "name": "<string>",
      "share": 0,
      "counterparty": "<string>",
      "color": "<string>"
    }
  ]
}

Can raise

401no valid token
403scope missing
404unknown or not visible
429rate limited

ALL CODES →

PUT/v1/assets/{asset_id}/segmentation

Put Segmentation

asset.write

Create or replace the segmentation design. Keeps the current status; bumps the version.

Path parameters

asset_idREQUIRED: string

Request body · required

modeREQUIRED: enumproportionalpriorityHow a physical shortfall is disaggregated across virtual assets. PROPORTIONAL: every segment shares the shortfall pro rata to its size. PRIORITY: segments are filled in ranking order; the lowest-ranked segments absorb the shortfall first (waterfall).
segmentsREQUIRED: array[object]

Example value

curl -X PUT "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation" \
  -H "Authorization: Bearer $EBX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"proportional","segments":[{"segment_id":"<string>","name":"<string>","share":0,"counterparty":"<string>","color":"<string>"}]}'

import httpx

r = httpx.put(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "mode": "proportional",
        "segments": [
            {
                "segment_id": "<string>",
                "name": "<string>",
                "share": 0,
                "counterparty": "<string>",
                "color": "<string>",
            },
        ],
    },
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"mode":"proportional","segments":[{"segment_id":"<string>","name":"<string>","share":0,"counterparty":"<string>","color":"<string>"}]}),
});
const data = await res.json();

Example response200

{
  "asset_id": "<string>",
  "mode": "proportional",
  "status": "draft",
  "version": 0,
  "updated_at": "2026-09-10T13:30:00Z",
  "segments": [
    {
      "segment_id": "<string>",
      "virtual_asset_id": "<string>",
      "name": "<string>",
      "share": 0,
      "counterparty": "<string>",
      "color": "<string>"
    }
  ]
}

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
422validation failed
429rate limited

ALL CODES →

DELETE/v1/assets/{asset_id}/segmentation

Delete Segmentation

asset.write

Remove the segmentation config; any virtual assets disappear from the fleet.

Path parameters

asset_idREQUIRED: string

Example value

curl -X DELETE "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.delete(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.status_code)

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Returns 204 with no body.

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
429rate limited

ALL CODES →

POST/v1/assets/{asset_id}/segmentation/activate

Activate Segmentation

asset.write

Activate the config: its segments appear as virtual assets in the fleet.

Path parameters

asset_idREQUIRED: string

Example value

curl -X POST "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation/activate" \
  -H "Authorization: Bearer $EBX_TOKEN"

import httpx

r = httpx.post(
    "https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation/activate",
    headers={"Authorization": f"Bearer {token}"},
)
print(r.json())

const res = await fetch("https://api.ebx.energy/v1/assets/DE_BESS_01/segmentation/activate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const data = await res.json();

Example response200

{
  "asset_id": "<string>",
  "mode": "proportional",
  "status": "draft",
  "version": 0,
  "updated_at": "2026-09-10T13:30:00Z",
  "segments": [
    {
      "segment_id": "<string>",
      "virtual_asset_id": "<string>",
      "name": "<string>",
      "share": 0,
      "counterparty": "<string>",
      "color": "<string>"
    }
  ]
}

Can raise

400malformed request
401no valid token
403scope missing
404unknown or not visible
409state conflict
429rate limited

ALL CODES →