Retrieve the lithology (ordered list of formations) for a design. The response describes each formation's type, name, and TVD depth interval.
Depth values are stored internally relative to RKB (Rotary Kelly Bushing). By default the API returns depths in RKB; pass ?depthReference=MSL to receive depths relative to Mean Sea Level — the server converts on the fly using the design's drill-floor height, ground elevation, and well configuration.
Get the lithology and ordered formations for a design
Path Parameters
| Name | Type | Required | Description |
|---|
designid | string (UUID) | ✓ | The UUID of the design |
Parameters
| Name | Type | Required | Description |
|---|
depthReference | string | - | Depth reference for returned TVD values. One of "RKB" or "MSL". Defaults to "RKB". |
Headers
| Name | Value | Description |
|---|
apikey | YOUR_API_KEY | Your API authentication key |
Query parameters
| Parameter | Type | Required | Description |
|---|
depthReference | string | No | RKB (default) or MSL. Controls the datum used for the returned topDepthTVD / bottomDepthTVD values. |
Response fields
| Field | Type | Description |
|---|
depthReference | "RKB" | "MSL" | Depth reference applied to the returned values. Echoes the depthReference query parameter, defaulting to RKB. |
formations | array | Ordered list of formations, top to bottom. See below. |
sv | string | Server version that produced the response. |
rc | string | Result code. "ok" on success. |
| Field | Type | Description |
|---|
index | integer | Zero-based position of the formation in the lithology, from top down. |
formationType | string | Rock type. Matches a name in the company's Formations library (e.g., Topsoil, Shale, Sandstone). |
name | string | Human-readable formation name (may be empty). |
topDepthTVD | string (unit-encoded) | Top TVD of the formation, e.g. "100|m". Returned in the requested depthReference. |
bottomDepthTVD | string (unit-encoded) | Bottom TVD of the formation, e.g. "1500|m". Returned in the requested depthReference. |
Notes
- Depth values are unit-encoded strings of the form
"<value>|<unit>", e.g. "1500|m". Parse with the @oliasoft-open-source/units helpers; do not split the pipe by hand.
- The
formations array is always returned in top-down order. The first formation's top is anchored to the seabed depth (water depth + drill-floor height); the last formation's bottom is clamped to the deepest trajectory point if a trajectory exists.
- For an unmodified design with no user edits,
formations contains a single default Rock formation (see Reset Lithology).
- When
depthReference=MSL is requested, RKB values are converted using the design's drill-floor height, ground elevation, and well configuration. The unit (m, ft) is preserved.