Dette dokumentet beskriver REN Grøft API (modultype CABLESIMULATOR), som brukes til å opprette og vedlikeholde grøftekonfigurasjoner i REN Grøft Design fra eksterne systemer.

Se REN Prosjekt API for det grunnleggende APIet, og Generelt for tilgang og autentisering.

APIet er under aktiv utvikling og dokumentasjonen kan endres. Se API Browser for oppdatert informasjon.
Dette dokumentet er avgrenset til dagens POC: opprette/slette delstrekning og legge til/slette kabel. APIet dekker også rør, jordledere, sensorer, kulverter, rørgrupper, kanalsystemer, grøftedeler, toppdekke, omgivelse og innstillinger - se den genererte referansen nederst på siden, eller API Browser, for disse.

Oppbygging

En delstrekning (trenchSegment, segmentId) er toppnivå-ressursen: ett grøftestrekk med navn og lengde. Den har alltid minst én grøftedel (section, sectionId) og ett nivå (layer, layerId) som kabler plasseres i - begge opprettes automatisk sammen med delstrekningen.

En kabel (cable, cableId) identifiseres med typeId fra katalogen. sectionId/layerId kan utelates ved opprettelse - serveren bruker da første grøftedel og underste nivå.

Base path

https://api.ren.no/public/cablesimulator/rest

Alle kall krever headerne api-version: 1.0 og Authorization: Bearer <token>.

Aktivering av grøftemodul

CABLESIMULATOR-modulen aktiveres via REN Prosjekt API (addModule). Kun liste (List trench segments in a project) og opprette (Create a new trench segment) sjekker dette, og svarer 409 Conflict hvis modulen ikke er aktivert.

Eksempler: delstrekning og kabel

1. Opprett delstrekning

POST /segments/by-projectid/12345 HTTP/1.1
api-version: 1.0
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "FV-HG-001",
  "length": 324
}

Svaret inneholder id (brukes som segmentId) og den automatisk opprettede grøftedelen/nivået - ta vare på disse IDene:

{
  "id": 98765,
  "name": "FV-HG-001",
  "length": 324.0,
  "sections": [
    {
      "id": "a3f2c1d0-8e4b-4f12-b7c3-d5e6f789abcd",
      "layers": [
        { "id": "b4e7d9f2-1c3a-4d56-8e7f-90a1b2c3d4e5", "cables": [] }
      ]
    }
  ]
}

2. Slå opp kabeltype

GET /catalog/cable-types?category=MV&componentSetScope=REN HTTP/1.1
api-version: 1.0
Authorization: Bearer <token>
[
  { "id": 1042, "name": "XLPE 240 mm² Al 12 kV", "voltageCategory": "MV" }
]

3. Legg til kabel

POST /segments/98765/trench/cables HTTP/1.1
api-version: 1.0
Authorization: Bearer <token>
Content-Type: application/json

{
  "typeId": 1042
}

4. Slett kabel

Ingen PUT for kabel - for å endre en kabel, slett og legg til på nytt.

DELETE /segments/98765/trench/cables/c5f8e1a3-... HTTP/1.1
api-version: 1.0
Authorization: Bearer <token>
Å slette én leder i en kabelgruppe sletter hele gruppen.

5. Slett delstrekning

Sletter delstrekningen og all underliggende grøftedata.

DELETE /segments/98765 HTTP/1.1
api-version: 1.0
Authorization: Bearer <token>

Statuskoder

Tabell 1. Statuskoder i REN Grøft API
Kode Betydning

400 Bad Request

Ugyldig kropp, manglende felt, felt over makslengde, eller manglende api-version-header.

401 Unauthorized

Manglende eller utløpt bearer-token.

403 Forbidden

Manglende rolle, eller - for en kjent segmentId - ingen tilgang til delstrekningens prosjekt.

404 Not Found

Ressursen finnes ikke: segmentId eller en komponent-ID inni den (f.eks. kabel-ID).

409 Conflict

På List trench segments in a project/Create a new trench segment: prosjektet finnes ikke, er utilgjengelig, eller mangler CABLESIMULATOR-modulen. På item-/grøftedel-endepunkter: samtidig endring (optimistisk låsing), eller forsøk på å slette siste grøftedel.

500 Internal Server Error

Generisk serverfeil. Kontakt REN IT hvis den vedvarer.

Strengfelter er begrenset til 255 tegn (1000 for description); brudd gir 400.

Full referanse

Den genererte referansen under dekker alle endepunkter i APIet - inkludert rør, jordledere (ECC), sensorer, kulverter, rørgrupper, kanalsystemer, lag, grøftedeler, toppdekke, omgivelse og innstillinger - som ikke inngår i dagens POC. Kan også utforskes interaktivt i API Browser.

Gå til API Browser

Resources

Trench Design Catalog

List cable types available in Trench Design
GET /catalog/cable-types
Description

Returns cable types available to the authenticated user (market access). Use componentSetScope to filter by ownership: REN for the official REN standard catalog, COMPANY for cables added by the authenticated company, USER for cables added by the authenticated user. Omit to return all accessible cable types regardless of ownership.

Parameters
Type Name Description Schema

Query

category
optional

Filter by cable category (ELV, LV, MV, HV, EHV, DC). Omit for all categories.

string

Query

componentSetScope
optional

Filter by component set ownership scope (REN, COMPANY, USER). REN = official REN catalog, COMPANY = company-specific, USER = user-specific.

string
Responses
HTTP Code Description Schema

200

Cable types accessible to the authenticated user

< CableType > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

oauth2

oauth2-client

tb.bruker
Get a cable type by REN internal ID
GET /catalog/cable-types/{cableTypeId}
Parameters
Type Name Schema

Path

cableTypeId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The cable type

CableType
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

oauth2

oauth2-client

tb.bruker
List ECC types (Earth Continuity Conductors) available in Trench Design
GET /catalog/ecc-types
Responses
HTTP Code Description Schema

200

ECC types accessible to the authenticated user

< EccType > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

oauth2

oauth2-client

tb.bruker
Get an ECC type by REN internal ID
GET /catalog/ecc-types/{eccTypeId}
Parameters
Type Name Schema

Path

eccTypeId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The ECC type

EccType
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

oauth2

oauth2-client

tb.bruker
List pipe types available in Trench Design
GET /catalog/pipe-types
Responses
HTTP Code Description Schema

200

Pipe types accessible to the authenticated user

< PipeType > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

oauth2

oauth2-client

tb.bruker

Trench Segment Items

Add a cable to a trench segment
POST /segments/{segmentId}/trench/cables
Description

Placed in the layer specified by layerId in the payload, or in the first (bottom) layer of the section specified by sectionId, or in the first section if both are omitted. Returns the cable with server-generated ID. Rejected with 400 if the cable type is not compatible with the trench design module (see CableType.cablesimulatorCompatible in the catalog).

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddCable
Responses
HTTP Code Description Schema

200

The created cable with server-generated ID

Cable
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add multiple identical power cables to a trench segment in one call
POST /segments/{segmentId}/trench/cables/batch
Description

Creates count independent cables of the same type/configuration/placement in a single internal write, instead of one addCable call per cable - use this when adding many cables at once (e.g. populating a large trench) to avoid one HTTP round-trip per cable. Placement (sectionId/layerId) works exactly like addCable. Returns all created cables with server-generated IDs. Rejected with 400 if the cable type is not compatible with the trench design module (see CableType.cablesimulatorCompatible in the catalog).

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddCableBatch
Responses
HTTP Code Description Schema

200

The created cables with server-generated IDs

< Cable > array
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a cable or cable group
GET /segments/{segmentId}/trench/cables/{cableId}
Description

Returns full placement properties for the specified cable or cable group, including computed layout values (clearOpeningLeft, clearOpeningRight, groundDist) and the catalog type name (typeName). Use the cable id from GET /segments/{segmentId}.

Parameters
Type Name Schema

Path

cableId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The cable

CableDetail
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Delete a cable from a trench segment
DELETE /segments/{segmentId}/trench/cables/{cableId}
Description

Deleting one conductor of a cable group deletes the whole group.

Parameters
Type Name Schema

Path

cableId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

204

The cable was deleted

No Content
Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a culvert (norsk: betongkanal / kulvert) to a trench segment
POST /segments/{segmentId}/trench/culverts
Description

Cables can be pre-placed inside the culvert by including them in the request body. Returns the culvert with server-generated ID. Rejected with 400 if any pre-placed cable’s type is not compatible with the trench design module (see CableType.cablesimulatorCompatible in the catalog).

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddCulvert
Responses
HTTP Code Description Schema

200

The created culvert with server-generated ID

Culvert
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a culvert (norsk: betongkanal / kulvert)
GET /segments/{segmentId}/trench/culverts/{culvertId}
Description

Returns dimensions, placement and read-only layout values for the specified culvert.

Parameters
Type Name Schema

Path

culvertId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The culvert

Culvert
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add an ECC (Earth Continuity Conductor) to a trench segment
POST /segments/{segmentId}/trench/eccs
Description

typeId can be omitted - the server uses the default ECC type. Returns the ECC with server-generated ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddEcc
Responses
HTTP Code Description Schema

200

The created ECC with server-generated ID

Ecc
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of an ECC (earth continuity conductor)
GET /segments/{segmentId}/trench/eccs/{eccId}
Description

Returns full placement properties for the specified ECC, including computed layout values (clearOpeningLeft, clearOpeningRight, groundDist) and the catalog type name (typeName). Use the ECC id from GET /segments/{segmentId}.

Parameters
Type Name Schema

Path

eccId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The ECC

EccDetail
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add an ecom duct (norsk: ekomkanal) to a trench segment
POST /segments/{segmentId}/trench/ecom-ducts
Description

Adds a telecom duct directly on a layer, or - via pipeId - inside an existing conduit pipe. A pipe only accepts ecom ducts (and sensors) inside it if it has pipeCategory=ECOM (see POST /pipes); rejected with 409 otherwise. Returns the ecom duct with server-generated ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddEcomDuct
Responses
HTTP Code Description Schema

200

The created ecom duct with server-generated ID

EcomDuct
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of an ecom duct (norsk: ekomkanal)
GET /segments/{segmentId}/trench/ecom-ducts/{ductId}
Description

Returns placement properties and read-only layout values for the specified ecom duct.

Parameters
Type Name Schema

Path

ductId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The ecom duct

EcomDuct
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a layer to a trench segment
POST /segments/{segmentId}/trench/layers
Description

Adds a new layer (norsk: niva) to the section identified by sectionId in the request body, or the first section in the segment if sectionId is omitted. Returns the layer with server-generated ID. Use the returned id as layerId when adding cables, pipes or ECCs to this layer.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddLayer
Responses
HTTP Code Description Schema

200

The created layer with server-generated ID

Layer
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Update spacing properties of a layer
PUT /segments/{segmentId}/trench/layers/{layerId}
Description

Updates protectionLayerThickness, leftBorderAdjustment and/or rightBorderAdjustment. Only non-null fields in the request body are applied. Returns the updated layer.

Parameters
Type Name Schema

Path

layerId
required

string

Path

segmentId
required

integer (int64)

Body

body
required

UpdateLayer
Responses
HTTP Code Description Schema

200

The updated layer

Layer
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a pipe canal system (norsk: kanalsystem) to a trench segment
POST /segments/{segmentId}/trench/pipe-canals
Description

Returns the pipe canal with server-generated ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddPipeCanal
Responses
HTTP Code Description Schema

200

The created pipe canal with server-generated ID

PipeCanal
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a pipe canal system (norsk: kanalsystem)
GET /segments/{segmentId}/trench/pipe-canals/{canalId}
Description

Returns channel count, placement and read-only layout values.

Parameters
Type Name Schema

Path

canalId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The pipe canal

PipeCanal
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a pipe group (norsk: rorgruppe) to a trench segment
POST /segments/{segmentId}/trench/pipe-groups
Description

Creates a group of identical conduit pipes in a defined arrangement (DOUBLE, TRIANGLE, TRIPPLE_FLAT). Returns the pipe group with server-generated ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddPipeGroup
Responses
HTTP Code Description Schema

200

The created pipe group with server-generated ID

PipeGroup
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a pipe group (norsk: rorgruppe)
GET /segments/{segmentId}/trench/pipe-groups/{groupId}
Description

Returns configuration, pipe type, placement and read-only layout values.

Parameters
Type Name Schema

Path

groupId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The pipe group

PipeGroup
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a pipe to a trench segment
POST /segments/{segmentId}/trench/pipes
Description

Cables can be pre-placed inside the pipe by including them in the request body - except for pipeCategory=ECOM, which only accepts ecom ducts and sensors inside it (see POST /ecom-ducts) and rejects pre-placed cables with 409. Returns the pipe with server-generated ID. Rejected with 400 if any pre-placed cable’s type is not compatible with the trench design module (see CableType.cablesimulatorCompatible in the catalog).

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddPipe
Responses
HTTP Code Description Schema

200

The created pipe with server-generated ID

Pipe
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a conduit pipe
GET /segments/{segmentId}/trench/pipes/{pipeId}
Description

Returns full placement properties for the specified pipe or pipe group, including computed layout values (clearOpeningLeft, clearOpeningRight, depth) and the catalog type name (typeName). Use the pipe id from GET /segments/{segmentId}.

Parameters
Type Name Schema

Path

pipeId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The pipe

PipeDetail
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a sensor to a trench segment
POST /segments/{segmentId}/trench/sensors
Description

Returns the sensor with server-generated ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddSensor
Responses
HTTP Code Description Schema

200

The created sensor with server-generated ID

Sensor
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get detailed properties of a sensor
GET /segments/{segmentId}/trench/sensors/{sensorId}
Description

Returns placement properties and read-only layout values for the specified sensor.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Path

sensorId
required

string
Responses
HTTP Code Description Schema

200

The sensor

Sensor
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

Trench Segment Structure

Add a section to a trench segment
POST /segments/{segmentId}/trench/sections
Description

Adds a new cross-section (norsk: grøftedel/tverrsnitt) to the segment. The server assigns a UUID and populates geometry defaults. Use beforeSectionId to insert before an existing section; omit to append at the end.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

CreateSection
Responses
HTTP Code Description Schema

200

The created section with server-generated ID

Section
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Update a section’s geometry properties
PUT /segments/{segmentId}/trench/sections/{sectionId}
Description

Updates the geometry of an existing section. Include only the fields to change. Omitted fields are left unchanged.

Parameters
Type Name Schema

Path

sectionId
required

string

Path

segmentId
required

integer (int64)

Body

body
required

UpdateSection
Responses
HTTP Code Description Schema

200

The updated section

Section
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Delete a section from a trench segment
DELETE /segments/{segmentId}/trench/sections/{sectionId}
Description

Deletes the section and all items (cables, pipes, ECCs) it contains. At least one section must remain; attempting to delete the last section returns 409.

Parameters
Type Name Schema

Path

sectionId
required

string

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

204

The section was deleted

No Content
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get segment-level trench settings
GET /segments/{segmentId}/trench/settings
Description

Returns the settings from the Innstillinger tab: snap distance, automatic protection markers, label length, etc.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The trench settings

TrenchSettings
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Update segment-level trench settings
PUT /segments/{segmentId}/trench/settings
Description

Patches the trench settings. Include only the fields to change.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

UpdateTrenchSettings
Responses
HTTP Code Description Schema

200

The updated trench settings

TrenchSettings
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get surroundings settings
GET /segments/{segmentId}/trench/surroundings
Description

Returns the terrain type and default soil thermal resistivity from the Omgivelse tab.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The surroundings settings

TrenchSurroundings
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Add a top covering to a segment
POST /segments/{segmentId}/trench/top-coverings
Description

Appends a new top covering (norsk: nytt toppdekke) to the segment. Defaults are applied for omitted fields. Returns the created covering with its server-assigned ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

AddTopCovering
Responses
HTTP Code Description Schema

200

The created top covering with server-generated ID

TopCovering
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
List top coverings for a segment
GET /segments/{segmentId}/trench/top-coverings
Description

Returns all top coverings (norsk: toppdekke) defined for the segment, in display order from bottom to top.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

200

The top coverings of the segment

< TopCovering > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Update a top covering
PUT /segments/{segmentId}/trench/top-coverings/{topCoveringId}
Description

Patches the top covering with the given ID. Include only the fields to change.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Path

topCoveringId
required

string

Body

body
required

UpdateTopCovering
Responses
HTTP Code Description Schema

200

The updated top covering

TopCovering
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Delete a top covering
DELETE /segments/{segmentId}/trench/top-coverings/{topCoveringId}
Description

Removes the top covering with the given ID from the segment.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Path

topCoveringId
required

string
Responses
HTTP Code Description Schema

204

The top covering was deleted

No Content
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

Trench Segments

Create a new trench segment
POST /segments/by-projectid/{projectId}
Description

Returns the segment with server-generated internal ID. name is limited to 255 characters, description to 1000 characters.

Parameters
Type Name Description Schema

Path

projectId
required

Project ID

integer (int64)

Body

body
required

CreateTrenchSegment
Responses
HTTP Code Description Schema

200

The created segment with server-generated ID

TrenchSegment
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
List trench segments in a project
GET /segments/by-projectid/{projectId}
Description

Returns segment metadata only (id, name, description, length) - not the trench configuration (sections). Fetch a specific segment by id (GET /segments/{segmentId}) for its full trench configuration.

Parameters
Type Name Schema

Path

projectId
required

integer (int64)
Responses
HTTP Code Description Schema

200

Segment metadata in the project

< TrenchSegment > array
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Get a trench segment with full trench configuration
GET /segments/{segmentId}
Description

segmentId is the unique internal ID (primary key).

Parameters
Type Name Description Schema

Path

segmentId
required

Segment ID

integer (int64)
Responses
HTTP Code Description Schema

200

The segment

TrenchSegment
Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Update trench segment metadata
PUT /segments/{segmentId}
Description

Updates name, description and length. Behaves as a partial update: fields omitted (null) are retained unchanged, so fields cannot be cleared to null. Trench configuration (sections) is modified via the item endpoints, not here. segmentId is the unique internal ID.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)

Body

body
required

UpdateTrenchSegment
Responses
HTTP Code Description Schema

200

The updated segment

TrenchSegment
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker
Delete a trench segment and all its trench data
DELETE /segments/{segmentId}
Description

Returns 404 if the segment does not exist.

Parameters
Type Name Schema

Path

segmentId
required

integer (int64)
Responses
HTTP Code Description Schema

204

The segment and its trench data were deleted

No Content
Security
Type Name Scopes

oauth2

oauth2-password

tb.bruker

Definitions

AddCable

Request body for adding a power cable to a trench section. Server-assigned fields are returned in the response.

Name Description Schema

groupConfiguration
optional

Physical layout of single-core conductors in the trench, describing how many conductors form this group and how they are arranged (e.g. SINGLE: a lone conductor; TRIANGLE: three in a trefoil). Not related to the cable type’s own conductor count. Omit to let the server pick a market-based default (typically three conductors in a trefoil).

enum (FLAT, TRIANGLE, TRIANGLE_MIRROR, TRIANGLE_PLUS_ONE, ONE_PLUS_TRIANGLE, SINGLE, PAIR, PAIR_MIRROR, CIRCLE, SQUARE, CUSTOM, FIXED)

layerId
optional

Id of the layer to place the cable in. Defaults to the first (bottom) layer of the resolved section if omitted. Not applicable for cables inside a pipe.

string

sectionId
optional

Id of the trench cross-section to place the cable in. Defaults to the first section if omitted. Not applicable for cables inside a pipe.

string

typeId
required

Cable type id from the catalog.
Example : 4711

integer (int64)

AddCableBatch

Request body for adding several identical power cables to a trench section in one call.

Name Description Schema

count
required

Number of independent cables to create with this type/configuration/placement.
Example : 20

integer (int32)

groupConfiguration
optional

Physical layout of single-core conductors in the trench. See AddCable.groupConfiguration for details. Applied identically to every created cable.

enum (FLAT, TRIANGLE, TRIANGLE_MIRROR, TRIANGLE_PLUS_ONE, ONE_PLUS_TRIANGLE, SINGLE, PAIR, PAIR_MIRROR, CIRCLE, SQUARE, CUSTOM, FIXED)

layerId
optional

Id of the layer to place the cables in. Defaults to the first (bottom) layer of the resolved section if omitted.

string

sectionId
optional

Id of the trench cross-section to place the cables in. Defaults to the first section if omitted.

string

typeId
required

Cable type id from the catalog.
Example : 4711

integer (int64)

AddCulvert

Request body for adding a culvert to a trench section, optionally with cables pre-placed inside it.

Name Description Schema

cables
optional

Cables to pre-place inside the culvert on creation. Max 50 per request.

< AddCable > array

height
optional

Inner height of the culvert in mm. Omit to use the server default.
Example : 400.0

number (double)

layerId
optional

Id of the layer to place the culvert in. Defaults to the first (bottom) layer of the first section if omitted.

string

width
optional

Inner width of the culvert in mm. Omit to use the server default.
Example : 600.0

number (double)

AddEcc

Request body for adding an earth continuity conductor (ECC) to a trench section.

Name Description Schema

layerId
optional

Id of the layer to place the ECC in. Defaults to the first (bottom) layer of the first section if omitted.

string

typeId
optional

ECC type id from the catalog. Omit to use the default ECC type.

integer (int64)

AddEcomDuct

Request body for adding an ecom duct to a trench section.

Name Description Schema

layerId
optional

Id of the layer to place the ecom duct in. Defaults to the first (bottom) layer of the first section if omitted. Ignored if pipeId is set.

string

outerDiameter
optional

Outer diameter of the ecom duct in mm. Omit to use the server default.
Example : 40.0

number (double)

pipeId
optional

Id of an existing conduit pipe to place this ecom duct inside, instead of directly on a layer. The pipe must have pipeCategory=ECOM - an ecom-category pipe only accepts ecom ducts and sensors, never power cables. Omit to place directly on a layer instead.

string

AddLayer

Request body for adding a layer to a trench section. After adding the layer, use its returned id as layerId when adding cables, pipes or ECCs to place items in this specific layer.

Name Description Schema

beforeLayerId
optional

Insert the new layer before the layer with this id. Omit to append the layer at the end (top) of the section.

string

protectionLayerThickness
optional

Thickness in mm of the protection material placed above this layer. Omit to use the server default.
Example : 50.0

number (double)

sectionId
optional

Id of the trench cross-section to add the layer to. Omit to use the first section in the segment.

string

AddPipe

Request body for adding a conduit pipe to a trench section, optionally with cables pre-placed inside it. Server-assigned fields are returned in the response.

Name Description Schema

cables
optional

Cables to pre-place inside the pipe on creation. Max 50 per request.

< AddCable > array

layerId
optional

Id of the layer to place the pipe in. Defaults to the first (bottom) layer of the first section if omitted.

string

pipeCategory
optional

Pipe category. CONTAINER (default): cable conduit. ECOM: telecommunications conduit. WATER: water pipe. SEWER: sewer pipe. HEAT: district heating pipe. GAS: gas pipe.

enum (CONTAINER, ECOM, WATER, SEWER, HEAT, GAS)

typeId
optional

Pipe type id from the catalog. Omit to let the server pick a default based on pipeCategory.
Example : 42

integer (int64)

AddPipeCanal

Request body for adding a pipe canal system to a trench section.

Name Description Schema

layerId
optional

Id of the layer to place the pipe canal in. Defaults to the first (bottom) layer of the first section if omitted.

string

partCount
required

Number of cable channels inside the pipe canal. Required.
Example : 4

integer (int32)

AddPipeGroup

Request body for adding a pipe group to a trench section. A pipe group arranges multiple pipes of the same type together.

Name Description Schema

configuration
required

Physical arrangement of the pipes. DOUBLE: two side by side. TRIANGLE: three in a triangle. TRIPPLE_FLAT: three in a flat row. Required.
Example : "DOUBLE"

enum (SINGLE, DOUBLE, TRIANGLE, TRIPPLE_FLAT)

layerId
optional

Id of the layer to place the pipe group in. Defaults to the first (bottom) layer of the first section if omitted.

string

pipeCategory
optional

Pipe category for all pipes in the group. CONTAINER (default): cable conduit.

enum (CONTAINER, ECOM, WATER, SEWER, HEAT, GAS)

typeId
optional

Pipe type id from the catalog. Omit to let the server pick a default based on pipeCategory.
Example : 42

integer (int64)

AddSensor

Request body for adding a sensor to a trench section.

Name Description Schema

layerId
optional

Id of the layer to place the sensor in. Defaults to the first (bottom) layer of the first section if omitted.

string

outerDiameter
optional

Outer diameter of the sensor in mm. Omit to use the server default.
Example : 40.0

number (double)

AddTopCovering

Properties for a new top covering. Defaults are applied by the server for omitted fields.

Name Description Schema

description
optional

User-defined description. Maximum 1000 characters.
Example : "Vegdekke"

string

infinite
optional

Whether the covering extends infinitely in width. Defaults to true if omitted.
Example : true

boolean

thermalResistivity
optional

Thermal resistivity in mK/W. Defaults to 1.0 mK/W if omitted.
Example : 1.0

number (double)

thickness
optional

Thickness in mm. Defaults to 100 mm if omitted.
Example : 100.0

number (double)

type
optional

Material type. Defaults to OTHER if omitted.

enum (TARMAC, CONCRETE, COBBLESTONE, GRAVEL, CRUSHED_STONES, SAND, OTHER)

Cable

A power cable placed directly in a trench cross-section or inside a conduit pipe.

Name Description Schema

cableCategory
optional
read-only

Voltage and current category of the cable. Read-only, derived from the cable type on creation.

enum (ELV, LV, MV, HV, EHV, DC)

displayName
optional
read-only

Human-readable display name for this cable, computed by the server and localised to the authenticated user’s language (e.g. "3x240 XLPE Cu/Al 12/20 kV"). Suitable for use in UI labels and export files without additional catalog lookups.

string

groupConfiguration
optional

Physical layout of the conductors. SINGLE: one single-core cable acting as one conductor. PAIR: two single-core cables. TRIANGLE: three single-core cables in trefoil arrangement. FLAT: three or more cables side by side. CUSTOM: user-defined layout. Omit to let the server derive the layout from the cable type’s conductor count.

enum (FLAT, TRIANGLE, TRIANGLE_MIRROR, TRIANGLE_PLUS_ONE, ONE_PLUS_TRIANGLE, SINGLE, PAIR, PAIR_MIRROR, CIRCLE, SQUARE, CUSTOM, FIXED)

id
optional
read-only

Unique server-assigned id of this cable object (String UUID). Use this id as a reference in fine-grained operations on the cable.

string

label
optional

Identification label shown in the trench diagram, e.g. K1, K2. Null means automatic labeling.
Example : "K1"

string

sectionId
optional

Id of the trench cross-section this cable is placed in. Used in fine-grained write operations; defaults to the first section.

string

typeId
required

Cable type id from the catalog.
Example : 4711

integer (int64)

CableBand

A cable band - a physical strap used to group or separate cables within a trench cross-section.

Name Description Schema

id
optional
read-only

Unique server-assigned id of this cable band (String UUID).

string

CableDetail

Detailed placement properties for a cable. Includes editable fields and read-only layout-computed values.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

groundDist
optional
read-only

Computed distance from the cable centre to ground level, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

groupConfiguration
optional

Physical layout of the conductors. Only set for single-core cable groups.

enum (FLAT, TRIANGLE, TRIANGLE_MIRROR, TRIANGLE_PLUS_ONE, ONE_PLUS_TRIANGLE, SINGLE, PAIR, PAIR_MIRROR, CIRCLE, SQUARE, CUSTOM, FIXED)

id
optional
read-only

Unique server-assigned id of the cable object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

partCount
optional

Number of single-core conductors in the group.
Example : 3

integer (int32)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

typeId
optional

Cable type id from the catalog.
Example : 4711

integer (int64)

typeName
optional
read-only

Cable type name from the catalog, e.g. "AXLJ-TT 12kV3x50/15AL". Read-only.

string

userLabel
optional

Operational label shown in the trench diagram.
Example : "K1"

string

xadjustment
optional

number (double)

yadjustment
optional

number (double)

CableType

A cable type available in the REN catalog. Use the id as typeId when adding cables to a trench segment.

Name Description Schema

cablesimulatorCompatible
optional

True if this cable type has a complete trench layout configuration and can be used in thermal load calculations.

boolean

conductorArea
optional

Conductor cross-section in mm².
Example : 95.0

number (double)

conductorCount
optional

Number of conductors. 1 = single-core, 3+ = multi-core.
Example : 3

integer (int32)

docCount
optional

Number of attached technical documents.
Example : 2

integer (int32)

generic
optional

True if this is a generic type not tied to a specific manufacturer. Generic types are used when the exact product is unknown.

boolean

id
optional

Unique catalog id. Use this as typeId when adding cables to a trench segment.
Example : 4711

integer (int64)

isolationLevel
optional

Insulation voltage level in kV.
Example : 0.6

number (double)

name
optional

Display name of the cable type.
Example : "TFXP 4x95 Al 0,6/1 kV"

string

outerDiameter
optional

Outer diameter in mm.
Example : 28.5

number (double)

voltageCategory
optional

Voltage category of the cable.

enum (ELV, LV, MV, HV, EHV)

CreateSection

Parameters for adding a new section to a trench segment. All fields are optional.

Name Description Schema

beforeSectionId
optional

If provided, the new section is inserted before this section. If omitted, the section is appended at the end of the segment.

string

CreateTrenchSegment

Request body for creating a trench segment. Server-assigned fields are returned in the response.

Name Description Schema

description
optional

Optional description. Maximum 1000 characters.

string

length
optional

Segment length in meters.
Example : 150.5

number (double)

name
required

Name of the trench segment. Maximum 255 characters.
Example : "UN-12345-GR-007"

string

Culvert

A culvert placed in a trench cross-section.

Name Description Schema

cables
optional

Power cables placed inside this culvert.

< Cable > array

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour in mm. Read-only.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour in mm. Read-only.

number (double)

depth
optional
read-only

Cover depth (norsk: overdekningsdybde) in mm: vertical distance from ground level to the top of this culvert. Computed by the server. Read-only.

number (double)

displayName
optional
read-only

Human-readable display name computed by the server.

string

height
optional

Inner height of the culvert in mm.
Example : 400.0

number (double)

id
optional
read-only

Unique server-assigned id of the culvert object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm (norsk: avstandskrav).
Example : 30.0

number (double)

positioning
optional

Horizontal positioning strategy (norsk: plassering).

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

width
optional

Inner width of the culvert in mm.
Example : 600.0

number (double)

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

Ecc

An earth continuity conductor (ECC) in a trench section. Installed alongside power cables to provide a continuous earthing path along the cable route.

Name Description Schema

displayName
optional
read-only

Human-readable display name for this ECC, computed by the server and localised to the authenticated user’s language (e.g. "Cu 35 mm²"). Suitable for use in UI labels and export files without additional catalog lookups.

string

id
optional
read-only

Unique server-assigned id of this ECC object (String UUID).

string

typeId
optional

ECC type id from the catalog. Omit to use the default ECC type.

integer (int64)

EccDetail

Detailed placement properties for an ECC (earth continuity conductor). Includes editable fields and read-only layout-computed values.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

displayName
optional
read-only

Human-readable display name for this ECC, computed by the server and localised to the authenticated user’s language (e.g. "Cu 35 mm2"). Suitable for use in UI labels and export files.

string

groundDist
optional
read-only

Computed distance from the ECC centre to ground level, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

id
optional
read-only

Unique server-assigned id of the ECC object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

typeId
optional

ECC type id from the catalog.
Example : 7

integer (int64)

typeName
optional
read-only

ECC type name from the catalog, e.g. "Cu 35 mm2". Read-only.

string

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

EccType

An earth continuity conductor (ECC) type. Use the id as typeId when adding an ECC to a trench section.

Name Description Schema

area
optional

Conductor cross-section in mm².
Example : 25.0

number (double)

id
optional

Unique catalog id. Use this as typeId when adding an ECC to a trench section.
Example : 5

integer (int64)

name
optional

Display name of the ECC type.
Example : "Cu 25 mm2"

string

radius
optional

Conductor radius in mm.
Example : 3.0

number (double)

EcomDuct

An ecom duct placed directly in a trench cross-section. Distinct from a telecom conduit pipe (pipeCategory=ECOM), which is a cable container.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour in mm. Read-only.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour in mm. Read-only.

number (double)

displayName
optional
read-only

Human-readable display name computed by the server.

string

groundDist
optional
read-only

Computed distance from the duct centre to ground level in mm. Read-only.

number (double)

id
optional
read-only

Unique server-assigned id of the ecom duct object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

outerDiameter
optional

Outer diameter of the ecom duct in mm.
Example : 40.0

number (double)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

Layer

A layer in a trench section. Layers are stacked vertically within the section. All cables, pipes and ECCs belong to exactly one layer.

Name Description Schema

cableBands
optional

Cable bands used to group or separate cables in this layer.

< CableBand > array

cables
optional

Power cables placed directly in this layer.

< Cable > array

culverts
optional

Culverts in this layer.

< Culvert > array

displayName
optional
read-only

Human-readable display name for this layer, computed by the server and localised to the authenticated user’s language.

string

eccs
optional

Earth continuity conductors (ECC) in this layer.

< Ecc > array

ecomDucts
optional

Ecom ducts in this layer.

< EcomDuct > array

id
optional
read-only

Unique server-assigned id of this layer (String UUID).

string

leftBorderAdjustment
optional

Extra distance in mm between items and the left trench wall.
Example : 20.0

number (double)

pipeCanals
optional

Pipe canal systems in this layer.

< PipeCanal > array

pipeGroups
optional

Pipe groups in this layer.

< PipeGroup > array

pipes
optional

Conduit pipes in this layer, optionally containing cables.

< Pipe > array

protectionLayerThickness
optional

Thickness in mm of the protection material placed above this layer before the next layer starts.
Example : 50.0

number (double)

rightBorderAdjustment
optional

Extra distance in mm between items and the right trench wall.
Example : 20.0

number (double)

sensors
optional

Sensors in this layer.

< Sensor > array

Pipe

A conduit pipe in a trench cross-section, optionally containing power cables.

Name Description Schema

cables
optional

Power cables placed inside this conduit pipe.

< Cable > array

depth
optional
read-only

Cover depth in mm: vertical distance from ground level to the top of this pipe. Computed by the server; null if the pipe has not been placed in the trench layout yet.
Example : 700.0

number (double)

displayName
optional
read-only

Human-readable display name for this pipe, computed by the server and localised to the authenticated user’s language (e.g. "PEL 110 mm"). Suitable for use in UI labels and export files without additional catalog lookups.

string

id
optional
read-only

Unique server-assigned id of this pipe object (String UUID). Use this id as a reference in fine-grained operations on the pipe.

string

pipeCategory
optional

Pipe category. CONTAINER (default): cable conduit. ECOM: telecommunications conduit. WATER: water pipe. SEWER: sewer pipe. HEAT: district heating pipe. GAS: gas pipe.

enum (CONTAINER, ECOM, WATER, SEWER, HEAT, GAS)

typeId
optional

Pipe type id from the catalog. If omitted, the server picks a default based on pipeCategory.
Example : 42

integer (int64)

PipeCanal

A pipe canal system placed in a trench cross-section. A multi-channel conduit unit with a configurable number of internal cable channels.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour in mm. Read-only.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour in mm. Read-only.

number (double)

depth
optional
read-only

Cover depth in mm. Computed by the server. Read-only.

number (double)

displayName
optional
read-only

Human-readable display name computed by the server.

string

id
optional
read-only

Unique server-assigned id of the pipe canal object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

partCount
optional

Number of cable channels inside the pipe canal.
Example : 4

integer (int32)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

PipeDetail

Detailed placement properties for a conduit pipe. Includes editable fields and read-only layout-computed values.

Name Description Schema

cables
optional

Power cables placed inside this conduit pipe.

< Cable > array

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour, in mm. Read-only, set by the layout engine. Null if not yet laid out.

number (double)

depth
optional
read-only

Cover depth in mm: vertical distance from ground level to the top of this pipe. Computed by the server; null if the pipe has not been placed in the trench layout yet.
Example : 700.0

number (double)

displayName
optional
read-only

Human-readable display name for this pipe, computed by the server and localised to the authenticated user’s language (e.g. "PEL 110 mm"). Suitable for use in UI labels and export files.

string

groupConfiguration
optional
read-only

Arrangement of pipes of the same type laid side by side. Only set for pipe groups.

enum (SINGLE, DOUBLE, TRIANGLE, TRIPPLE_FLAT)

id
optional
read-only

Unique server-assigned id of the pipe object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

pipeCategory
optional
read-only

Pipe category. Read-only after creation.

enum (CONTAINER, ECOM, WATER, SEWER, HEAT, GAS)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

typeId
optional

Pipe type id from the catalog.
Example : 42

integer (int64)

typeName
optional
read-only

Pipe type name from the catalog, e.g. "PEL 110 mm". Read-only.

string

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

PipeGroup

A pipe group in a trench cross-section: multiple conduit pipes of the same type laid together in a defined arrangement.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour in mm. Read-only.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour in mm. Read-only.

number (double)

configuration
optional

Physical arrangement of the pipes in the group.
Example : "DOUBLE"

enum (SINGLE, DOUBLE, TRIANGLE, TRIPPLE_FLAT)

depth
optional
read-only

Cover depth in mm. Computed by the server. Read-only.

number (double)

displayName
optional
read-only

Human-readable display name computed by the server.

string

id
optional
read-only

Unique server-assigned id of the pipe group object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

pipeCategory
optional
read-only

Pipe category of the pipes in the group.

enum (CONTAINER, ECOM, WATER, SEWER, HEAT, GAS)

pipeCount
optional
read-only

Number of pipes in the group, derived from the configuration. Read-only.
Example : 2

integer (int32)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

typeId
optional

Pipe type id from the catalog applied to all pipes in the group.
Example : 42

integer (int64)

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

PipeType

A conduit pipe type from the catalog. Use the id as typeId when adding a pipe to a trench section.

Name Description Schema

id
optional

Unique catalog id. Use this as typeId when adding a pipe to a trench section.
Example : 42

integer (int64)

name
optional

Display name of the pipe type.
Example : "PE pipe 110 SDR11"

string

outerDiameter
optional

Outer diameter in mm.
Example : 110.0

number (double)

wallThickness
optional

Wall thickness in mm.
Example : 10.0

number (double)

Section

A trench cross-section within a segment. Each section defines the geometry of the trench and holds one or more layers. All cables, conduit pipes and earth continuity conductors (ECC) belong to exactly one layer.

Name Description Schema

coverThickness
optional

Cover depth in mm: thickness of the backfill layer above the uppermost cable or pipe.
Example : 100.0

number (double)

displayName
optional
read-only

Human-readable display name for this section, computed by the server and localised to the authenticated user’s language. Suitable for use in UI labels and export files without additional catalog lookups.

string

foundationThickness
optional

Foundation thickness for the cable zone in mm.
Example : 50.0

number (double)

foundationThicknessFillZone
optional

Foundation thickness for the fill zone in mm.
Example : 50.0

number (double)

id
optional
read-only

Unique server-assigned id of this section (String UUID). Use this id as a reference in fine-grained operations on the section.

string

layers
optional

Layers stacked vertically in this section, bottom first. Each layer contains the cables, pipes and ECCs placed at that vertical level.

< Layer > array

layoutDepth
optional

Laying depth in mm: vertical distance from ground level to the center of the cable zone.
Example : 800.0

number (double)

leftBorderPadding
optional

Distance from cables/items to the left trench wall in mm.
Example : 50.0

number (double)

rightBorderPadding
optional

Distance from cables/items to the right trench wall in mm.
Example : 50.0

number (double)

sectionType
optional

Cross-section type. STANDARD_TRENCH (default): standard uniform trench cross-section. ADVANCED_TRENCH: extended configuration with additional geometry parameters. DIRECTLY_IN_GROUND: cable laid directly in the ground without a constructed trench.

enum (STANDARD_TRENCH, ADVANCED_TRENCH, DIRECTLY_IN_GROUND)

Sensor

A sensor placed in a trench cross-section.

Name Description Schema

clearOpeningLeft
optional
read-only

Computed clear opening to the left neighbour in mm. Read-only.

number (double)

clearOpeningRight
optional
read-only

Computed clear opening to the right neighbour in mm. Read-only.

number (double)

displayName
optional
read-only

Human-readable display name computed by the server.

string

groundDist
optional
read-only

Computed distance from the sensor centre to ground level in mm. Read-only.

number (double)

id
optional
read-only

Unique server-assigned id of the sensor object (String UUID).

string

minPadding
optional

Minimum required clear opening to adjacent items, in mm.
Example : 30.0

number (double)

outerDiameter
optional

Outer diameter of the sensor in mm.
Example : 40.0

number (double)

positioning
optional

Horizontal positioning strategy.

enum (AUTOMATIC, MINIMUM_CLEAR_OPENING, FIXED_CLEAR_OPENING, SNAP_TO_NEAREST, SNAP_TO_ITEM, FREE_AUTOMATIC, FREE_MANUAL)

xAdjustment
optional

number (double)

yAdjustment
optional

number (double)

TopCovering

Top covering above the trench. Affects heat dissipation to ambient and thermal ampacity calculations.

Name Description Schema

description
optional

User-defined description of this top covering.
Example : "Vegdekke vest"

string

id
optional
read-only

Server-assigned UUID of this top covering.

string

infinite
optional

If true, the covering extends infinitely in width beyond the trench When false, a finite width must be specified.
Example : true

boolean

thermalResistivity
optional

Thermal resistivity of this covering in mK/W.
Example : 1.0

number (double)

thickness
optional

Thickness in mm.
Example : 100.0

number (double)

type
optional

Material type of the top covering.

enum (TARMAC, CONCRETE, COBBLESTONE, GRAVEL, CRUSHED_STONES, SAND, OTHER)

TrenchSegment

A trench segment (norsk: delstrekning) - the top-level resource in the Trench Design API. A segment represents a physical section of a cable route from one connection point to the next. The server-assigned id is the primary key for all operations.

Name Description Schema

description
optional

Optional description.

string

id
optional
read-only

Unique server-assigned id of the trench segment. Use this id in all subsequent read, update and delete operations.
Example : 98765

integer (int64)

length
required

Route length (norsk: strekningslengde) in meters.
Example : 150.5

number (double)

name
required

Name of the trench segment. Can be used as an optional external reference key and looked up via the by-name endpoint. Must be unique within the project if used for lookups. Avoid renaming segments that are managed through the API.
Example : "EX-12345-GR-007"

string

projectId
optional

Id of the REN project this trench segment belongs to. Populated when the segment was reached through a project-scoped endpoint (list, create, by-name). Omitted when fetched or updated directly by segmentId, since the API has no way to resolve a segment’s project from its id alone.
Example : 12345

integer (int64)

sections
optional

Trench cross-sections (norsk: tverrsnitt) in this segment. Present in the single-segment detail endpoint and in create/update responses. Omitted (null) in list-by-project responses - use GET /segments/{segmentId} to retrieve a specific segment’s sections with full content.

< Section > array

validationErrors
optional

Validation errors in the trench configuration (norsk: valideringsfeil). Present when the layout engine detects problems such as overlapping items or items placed outside their container. Empty list means the configuration is valid. Only populated in the single-segment detail endpoint.

< TrenchValidationError > array

TrenchSettings

Trench segment settings. Applies to the whole trench configuration, not a single section.

Name Description Schema

autoMarkers
optional

Whether automatic protection markers are enabled (norsk: automatisk markering/beskyttelse).
Example : true

boolean

defaultMarkerTypeId
optional

Default marker/protection type ID from the catalog (norsk: standard markering/beskyttelse).
Example : 42

integer (int64)

maxDistUncoveredByAutoMarkers
optional

Maximum distance in mm not covered by automatic protection markers (norsk: maks avstand udekket av automatisk markering).
Example : 200.0

number (double)

maxSnapDist
optional

Maximum snap distance in mm. Controls how close items must be to snap to each other automatically.
Example : 50.0

number (double)

shortLabelMaxLength
optional

Maximum character length for short operational labels (norsk: maks lengde for driftsmerking (kort)).
Example : 20

integer (int32)

TrenchSurroundings

Surroundings settings (norsk: omgivelse) for the trench segment. Terrain type affects the thermal model; thermal resistivity is the default soil value used in ampacity calculations (IEC 60287).

Name Description Schema

fillZoneThermalResistivity
optional

Default fill zone thermal resistivity in mK/W. Represents the surrounding soil. Used as the default for zones without an explicit material.
Example : 2.5

number (double)

terrainType
optional

Terrain type. SIMPLE = flat and uniform (norsk: flatt og uniformt); ADVANCED = custom terrain profile (norsk: egendefinert).

enum (SIMPLE, ADVANCED)

TrenchValidationError

A validation error in the trench configuration. Present when the layout engine detects problems such as overlapping items or items placed outside their container.

Name Description Schema

itemDisplayName
optional
read-only

Display name of the item or item pair with the error. Localised to the authenticated user’s language.
Example : "HS kabelgruppe (AC) @ niva A1.2 #2.1"

string

message
optional
read-only

Human-readable description of the error. Localised to the authenticated user’s language.
Example : "Ligger utenfor objektet som det er plassert i."

string

severity
optional
read-only

Severity of the error.

enum (OK, INVALID, MISSINGINPUT)

UpdateLayer

Request body for updating spacing properties of a layer (norsk: niva). Only non-null fields are applied; omitted fields are left unchanged.

Name Description Schema

leftBorderAdjustment
optional

Extra distance in mm between the items in this layer and the left trench wall. Defaults to 0 if omitted on layer creation.
Example : 20.0

number (double)

protectionLayerThickness
optional

Thickness in mm of the protection material (norsk: beskyttelsesmasse) placed above this layer before the next layer starts. Set to null to clear (reset to server default).
Example : 50.0

number (double)

rightBorderAdjustment
optional

Extra distance in mm between the items in this layer and the right trench wall. Defaults to 0 if omitted on layer creation.
Example : 20.0

number (double)

UpdateSection

Fields to update on an existing trench section (norsk: grøftedel/tverrsnitt). Include only the fields you want to change.

Name Description Schema

coverThickness
optional

Cover depth (norsk: overdekningsdybde) in mm: thickness of backfill above the top of the cable zone.
Example : 100.0

number (double)

foundationThickness
optional

Sand bed thickness (norsk: tykkelse fundament, ledningssone) in mm.
Example : 50.0

number (double)

foundationThicknessFillZone
optional

Sand bed thickness for the fill zone (norsk: tykkelse fundament, gjenfyllingssone) in mm.
Example : 50.0

number (double)

leftBorderPadding
optional

Distance (norsk: avstand til venstre kantlinje) in mm between items and the left trench wall.
Example : 50.0

number (double)

rightBorderPadding
optional

Distance (norsk: avstand til høyre kantlinje) in mm between items and the right trench wall.
Example : 50.0

number (double)

UpdateTopCovering

Fields to update on an existing top covering (norsk: toppdekke). Include only the fields you want to change.

Name Description Schema

description
optional

User-defined description (norsk: navn/beskrivelse). Maximum 1000 characters.
Example : "Vegdekke"

string

infinite
optional

Whether the covering extends infinitely in width.
Example : true

boolean

thermalResistivity
optional

Thermal resistivity in mK/W.
Example : 1.0

number (double)

thickness
optional

Thickness in mm.
Example : 100.0

number (double)

type
optional

Material type (norsk: type).

enum (TARMAC, CONCRETE, COBBLESTONE, GRAVEL, CRUSHED_STONES, SAND, OTHER)

UpdateTrenchSegment

Request body for updating trench segment metadata. Fields that are omitted (null) are kept unchanged.

Name Description Schema

description
optional

New description. Maximum 1000 characters.

string

length
optional

New route length (norsk: strekningslengde) in meters.
Example : 150.5

number (double)

name
optional

New name of the trench segment. Maximum 255 characters.
Example : "UN-12345-GR-007"

string

UpdateTrenchSettings

Fields to update on the trench settings. Include only the fields you want to change.

Name Description Schema

autoMarkers
optional

Enable automatic protection markers (norsk: automatisk markering/beskyttelse).
Example : true

boolean

defaultMarkerTypeId
optional

Default marker/protection type ID.
Example : 42

integer (int64)

maxDistUncoveredByAutoMarkers
optional

Maximum distance in mm not covered by automatic protection markers.
Example : 200.0

number (double)

maxSnapDist
optional

Maximum snap distance in mm.
Example : 50.0

number (double)

shortLabelMaxLength
optional

Maximum character length for short operational labels.
Example : 20

integer (int32)

Security

oauth2-password

A flow where an end user is required. Endpoints using this flow can provide personal customization and access to personal information.

Type : oauth2
Flow : password
Token URL : https://www.ren.no/auth/realms/www.ren.no/protocol/openid-connect/token

Name Description

tb.bruker

Implies that role 'tb.bruker' is required.

oauth2-client

A flow where an end user is not involved. Endpoints using this flow will support full automation without any human intervention, but on the other hand cannot provide personal customization or access to personal information.

Type : oauth2
Flow : application
Token URL : https://www.ren.no/auth/realms/www.ren.no/protocol/openid-connect/token

Name Description

tb.bruker

Implies that role 'tb.bruker' is required.