The underground gateway is the conversational entrypoint for the Underground Engineering Agent. It uses the same SSE contract as the overhead gateway and exposes the 68 MCP tools that operate on the Universal Vault Model — vault assembly, conduit routing, fill, pulling tension, ampacity, fault current, network topology, and OH→UG conversion studies.

Base URL: https://hv-pole-platform-dev.web.app/api/ug

Endpoints

The endpoint shape mirrors the overhead gateway one-for-one. Anything documented for /api exists at /api/ug for the underground domain.

PathPurpose
POST /chatStream a chat turn against the underground tool catalog.
POST /sessionsCreate or update a session backed by a Universal Vault Model.
GET /vault-modelRetrieve the active vault model as JSON.
POST /uploadIngest a vault / conduit JSON payload.
GET /upload-urlSigned GCS URL for browser-side PUT.
GET /download and POST /exports/{filename}Retrieve generated outputs (USD scene, conversion study PDFs, etc.).

Differences from the overhead gateway

  • The active model is a Universal Vault Model, not a Universal Pole Model.
  • The tool catalog is sized 68 (vs. 75 overhead) and covers different domains: ampacity, pulling tension, conduit fill, fault current, duct bank, network topology.
  • A unified circuit-graph endpoint (POST /chat with the right tool call) merges overhead and underground nodes for path-finding, redundancy, and conversion candidates. This is the only place the two domains cross.

A typical conversion study

A common workflow against this gateway is an OH→UG conversion study:

curl -N https://hv-pole-platform-dev.web.app/api/ug/chat \
  -H "Authorization: Bearer $VERTICAL_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ug-conv-1",
    "message": "Run an OH-to-UG conversion study for line 318. Suggest vault placement, check pulling feasibility, and price it."
  }'

The agent will call (in order, roughly): analyze_circuit_for_conversion, recommend_vault_placement, pulling_feasibility, riser_design, and cost_estimate — and return a single bundled finding with vault locations, pulling tensions, riser equipment, and a budgetary estimate.

See also