Replace Lithology

Replace the entire lithology for a design with the supplied list of formations. The request is a full replacement — the existing formations are discarded and re-created from the payload.

The server validates that the supplied formations form a gap-free column: each formation's bottomDepthTVD must equal the next formation's topDepthTVD. The server also enriches every formation row with density, specific heat, and thermal conductivity values looked up from the company's Formations library, keyed by formationType. The first formation's top is anchored to the seabed depth, and the last formation's bottom is clamped to the deepest trajectory point if a trajectory exists.

PUT/api/v1/designs/{designid}/lithology

Replace the lithology and its formations for the design

Path Parameters

Name	Type	Required	Description
designid	string (UUID)	✓	The UUID of the design

Headers

Name	Value	Description
apikey	YOUR_API_KEY	Your API authentication key
Content-Type	application/json	Must be application/json

Request Body

Lithology payload with an ordered, gap-free list of formations

Request body fields

Field	Type	Required	Description
lithologyId	string (UUID)	No	Optional lithology identifier. Echoed for clients that track lithology IDs; the server does not require it.
depthReference	"RKB" | "MSL"	No	Datum used for the topDepthTVD / bottomDepthTVD values in this payload. Defaults to RKB. If MSL, the server converts to RKB before persisting.
formations	array	Yes	Ordered list of formations, top to bottom. Must be gap-free (see below).

Formation fields

Field	Type	Required	Description
formationId	string (UUID)	No	Optional formation identifier; ignored on write.
index	integer	No	Position hint. The server re-indexes formations from 0 in array order.
formationType	string	Yes	Rock type. Must exist as a name in the Formations library for the company — used to look up density, specific heat, and thermal conductivity. Examples: Topsoil, Shale, Sandstone, Limestone, Rock.
name	string	Yes	Human-readable formation name. May be empty.
topDepthTVD	string (unit-encoded)	Yes	Top TVD, e.g. "100|m".
bottomDepthTVD	string (unit-encoded)	Yes	Bottom TVD, e.g. "1500|m".

Gap-free coverage

Consecutive formations in formations must connect: for every adjacent pair (a, b), a.bottomDepthTVD must equal b.topDepthTVD (after unit conversion). If any gap is detected the request is rejected with 400 and a message listing the offending pairs, e.g. "There are gaps in the provided formations. The gaps are between: formation 0 (Topsoil, "Quaternary") and formation 1 (Shale, "Hordaland")".

The server overrides two depth endpoints regardless of input:

• The first formation's topDepthTVD is set to the seabed depth (water depth + drill-floor height) of the design.
• The last formation's bottomDepthTVD is clamped to the deepest trajectory TVD if a trajectory exists, otherwise collapsed to its top depth.

Notes

• Unit-encoded values use the form "<value>|<unit>", e.g. "1500|m". Build them with @oliasoft-open-source/units helpers — do not concatenate strings by hand.
• The response on success is the persisted lithology in the same shape as GET /lithology, including the server-applied seabed and trajectory clamps.
• Each formation row is enriched server-side with density (Ro), specific heat (Cp), and thermal conductivity (Lambda) looked up from the Formations library by formationType. If a formationType has no library entry, the row is persisted without those enrichments.
• To revert to a single default Rock formation, see Reset Lithology.