---
name: STAGESHARE_SURVEY
for: wellscope.stageshare/1.0.0
homepage: https://dx.horizontalwireline.ai/STAGESHARE_SURVEY.md
---

# Stage Share directional survey

Pad well paths for the guest overlay. **2D** sits in a small strip above chat. Click opens **3D**. An orange bubble marks the current tool on the active well.

Canonical: `GET https://dx.horizontalwireline.ai/STAGESHARE_SURVEY.md`

Not `/v1/inbound`. Not partner `/v1/logs`. Privilege `stageshare`. Contract stays `wellscope.stageshare/1.0.0`.

**Pi: snapshot the pad on room create.** Send `survey` on `POST /v1/stageshare/rooms` next to `customer` / `pad` / `well` / `stage` / `truck`. Each Stage Share is standalone (LAS + thread + survey). The `ss_` link is a capability key only — never put stations in the URL. Do not resend the pad on every pointer. New stage = new room = send the survey again.

`PUT /v1/stageshare/rooms/{id}/survey` is for a late attach or a correction after create.

## Datum

`datum` is always **`ground`**.

- **0 ft TVD = ground / surface**
- Positive TVD is below ground
- Negative TVD is above ground (kelly bushing / stickup)
- `kb_ft` is optional and informational (KB height above ground). Do **not** add it to TVD. If the first station is MD/TVD = −15, send `kb_ft: 15` and leave those TVDs negative.

Measured depth (`md`) is along-hole. The bubble label is **MD**. The 3D/2D position is interpolated from the survey at that MD.

`ns` / `ew` are feet from **that well’s wellhead**. Optional `surface_ns_ft` / `surface_ew_ft` place the wellhead on the pad so several wells do not stack at the origin.

## Create (preferred)

```
POST /v1/stageshare/rooms
Authorization: Bearer hwx_…
WellScope-Contract: wellscope.stageshare/1.0.0
Content-Type: application/json
```

Body cap **512 KiB**. Max **16** wells, **2500** stations each. Omit `survey` to create a room without a pad (guest hides the strip until a later PUT).

```
{
  "customer": "Operator",
  "pad": "Longwell North",
  "well": "Longwell 7H",
  "stage": "56",
  "truck": "12",
  "unit_label": "Cabin",
  "ttl_frozen_hours": 72,
  "survey": {
    "datum": "ground",
    "kb_ft": 15,
    "active_well": "Longwell 7H",
    "wells": [
      {
        "name": "Longwell 7H",
        "uid": "L-004743",
        "surface_ns_ft": 160,
        "surface_ew_ft": 80,
        "cols": ["md", "inc", "azm", "tvd", "vs", "ns", "ew", "dls"],
        "stations": [
          [-15, 0, 151.8, -15, 0, 0, 0, 0],
          [100, 0.21, 151.8, 100, -0.21, -0.19, 0.1, 0.18]
        ]
      }
    ]
  }
}
```

`201` includes `has_survey`, `well_count`, `active_well`, `station_count` when a survey was stored. Bad survey is `400` / `413` and **does not create the room**.

## PUT (late attach / correction)

```
PUT /v1/stageshare/rooms/{id}/survey
Authorization: Bearer hwx_…
Content-Type: application/json
```

Body is the survey object itself (same shape as the `survey` key on create — `{ "datum", "wells", … }`, not wrapped again). Replace the whole pad (not a patch). Counts as a truck handshake. Same 512 KiB / 16 wells / 2500 stations limits.

## Station format

Preferred compact rows — same column order as a typical directional export:

`cols: ["md", "inc", "azm", "tvd", "vs", "ns", "ew", "dls"]` then `stations: [[md, inc, azm, tvd, vs, ns, ew, dls], …]`.

Required per station after mapping: **`md`, `tvd`, `ns`, `ew`**. `inc` / `azm` / `vs` / `dls` are optional (`inc` ≥ 80 draws lateral beads). Object stations are accepted (`{ "md", "tvd", "ns", "ew", "inc", "azm" }`). Aliases: `incl`, `azi`, `north_ft`, `east_ft`.

`active_well` must match a `wells[].name`. Guest uses it for the tool bubble; live `tool_depth_ft` / pointer `depth_ft` is the MD. Changing the bubble does **not** require rewriting stations.

DX always echoes `cols: ["md","inc","azm","tvd","vs","ns","ew","dls"]` and 8-wide station arrays.

`400` `invalid_survey` / `wells_required` / `stations_required` / `well_name_required`. `413` `too_many_wells` / `too_many_stations`.

## GET

```
GET /v1/stageshare/rooms/{id}/survey
Authorization: Bearer hwx_…   or   Bearer sst_…
```

`200 { "survey": { … } | null }`. Room GET also has `has_survey`. Overlay hello includes the full `survey` object. WS `{ "type": "survey", "payload": { "survey": {…} | null } }`. Snapshot zip includes `survey.json` when present.

`DELETE` the same path (operator) clears it.

## Guest

Do not fetch the Pi. After create (or PUT), the overlay draws 2D above chat and 3D on click. The bubble follows `view_hint.tool_depth_ft` (same MD Follow uses). Gold Edge/cabin cursors do not move the survey bubble.

## 2D vs 3D

2D is an estimate: the guest plots TVD down vs the larger of the pad’s NS or EW span. Laterals do not have to share an azimuth — use 3D for the pad. Do not send a camera or screen pixels.