# 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.

API reference

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\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

```typescript
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 response · 200

```json
{ · 
   · "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

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

 · 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\_id · REQUIRED

string

Request body · required

mode · REQUIRED

enum · `proportional` · `priority` · How 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).

segments · REQUIRED

array\[object\]

Example value

cURL:

```bash
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>"}]}'
```

Python:

```python
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())
```

TypeScript:

```typescript
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 response · 200

```json
{ · 
   · "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

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)· DELETE · /v1/assets/{asset\_id}/segmentation

### Delete Segmentation

asset.write

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

Path parameters

asset\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

```typescript
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

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)

· 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\_id · REQUIRED

string

Example value

cURL:

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

Python:

```python
import ·  httpx

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

TypeScript:

```typescript
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 response · 200

```json
{ · 
   · "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

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

[ALL CODES →](https://docs.ebx.energy/reference/errors.md)