HWireline Data Exchange

Partner telemetry API. This hostname is not the job board and has no admin UI. Production access is granted from the Tailscale admin console.

Agents: GET /skill.json at the start of every task, then HWS_DATA_SKILL v1 if the version moved (/llms.txt). Demo: time log · LAS viewer.

OpenAPI 3
skill.json — agents MUST fetch this at the start of every task
HWS_DATA_SKILL v1 (canonical skill; reload if skill.json version changed)
STAGESHARE_THREAD.md · SURVEY · UPLINK · LOGS
llms.txt (for agents)
GET /v1/catalog (requires API key)
Sample key signup / lost key
Browser demo (paste a key, GET/POST from the page)
LAS log viewer (WellScope-style depth plot; GET /v1/logs)

Stage Share (skill 1.5.19, contract wellscope.stageshare/1.0.0): a live WellScope stage overlay — room-scoped LAS, depth pins, and cursors — not truck telemetry. Privilege stageshare is not write. Create with header WellScope-Contract: wellscope.stageshare/1.0.0; 201 includes { "contract": { "accepted": "1.0.0" } }. DX sends invite email when mail.sender is dx. Guests open https://horizontalwireline.ai/stageshare/{ss_…} (no API key). Overlay is /v1/stageshare/stream, not /v1/stream. Room LAS is isolated from /v1/logs and /v1/inbound.

Agents: with a guest ss_ link, POST /v1/stageshare/sessions then list …/logs and …/comments (JSON array of pins at depth_ft). With hwx_ and privilege stageshare, start at GET /v1/stageshare/rooms. Pointers are well-space (depth_ft, column_id, x_frac) — never screen pixels. Pi uplink (stay LIVE on surface + live_tail CCLR lead; guest Follow is tool MD): STAGESHARE_UPLINK.md. LAS promote / Sync / resend / inject: STAGESHARE_LOGS.md. Chat vs depth comments: STAGESHARE_THREAD.md. Pad survey: STAGESHARE_SURVEY.md. See HWS_DATA_SKILL.

Auth

Authorization: Bearer hwx_…

First calls

curl -sS https://dx.horizontalwireline.ai/openapi.json
curl -sS -H "Authorization: Bearer $HWX_API_KEY" https://dx.horizontalwireline.ai/v1/catalog
curl -sS -H "Authorization: Bearer $HWX_API_KEY" https://dx.horizontalwireline.ai/v1/logs
curl -sS -H "Authorization: Bearer $HWX_API_KEY" https://dx.horizontalwireline.ai/v1/telemetry/latest

LAS files are stored in object storage. GET /v1/logs returns placeholders (storage.uri + storage.href). Fetch the LAS 2.0 body from /v1/logs/{id}/content, or downsampled plot series from /v1/logs/{id}/curves. History requires from and to (ISO, max 7 days). Live SSE: POST /v1/stream-tokens, then EventSource on stream_url. Never put hwx_ in the URL.

POST /v1/inbound

Requires privilege write. Stores JSON for HWireline in isolated dx.inbound_payloads — never merged into truck telemetry. Response 201 { id, topic, received_at }. List your posts with GET /v1/inbound?limit=50.

Option A — topic + payload (preferred)

curl -sS -X POST https://dx.horizontalwireline.ai/v1/inbound \
  -H "Authorization: Bearer $HWX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"well-file","payload":{"well":"8H","stage":37,"note":"from partner"}}'

Option B — flat object (topic optional, default inbox; every other key is the payload)

curl -sS -X POST https://dx.horizontalwireline.ai/v1/inbound \
  -H "Authorization: Bearer $HWX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"well":"8H","stage":37,"note":"from partner"}'

Option C — array payload

curl -sS -X POST https://dx.horizontalwireline.ai/v1/inbound \
  -H "Authorization: Bearer $HWX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"events","payload":[{"well":"8H"},{"well":"2H"}]}'

topic: 1–128 characters [A-Za-z0-9._/-]. Payload: JSON object or array, max ~200 KiB. 400 bad body, 403 no write privilege.

POST /v1/recommendations

Any valid API key (sample keys included). Privilege write is not required. Agents use this to suggest product or docs changes — for example sharing LAS files. HWireline reviews by hand; not every suggestion ships. This is not /v1/inbound.

curl -sS -X POST https://dx.horizontalwireline.ai/v1/recommendations \
  -H "Authorization: Bearer $HWX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"It would be great if you can share LAS files for every completed stage.","context":"User asked for collar depths","source":"Cursor"}'

Response 201 { id, message, status, received_at }. List yours with GET /v1/recommendations. After a suggestion is accepted and shipped, the skill version in /skill.json bumps.

Paging

/v1/telemetry returns an opaque cursor encoding (time, truck_number). Send it back verbatim as ?cursor=…; null means you have the last page.

Admin API (privilege admin)

The Tailscale console is the only super-user path that can grant privilege admin. Keys with that privilege call /v1/admin. Every mutation emails a 6-digit code to the acting admin; confirm at POST /v1/admin/intents/{id}/confirm or /intent-confirm. Cannot grant admin. Secrets are never emailed.

Keys expire

Every key carries an expires_at; sample keys last 30 days. After that every endpoint answers 401. Any party with a registered email can mint a replacement from Lost key. The reset mail never includes the secret.