The overhead gateway is the conversational entrypoint for the Pole Analysis Agent. It wraps an LLM around the 75 MCP tools that operate on the Universal Pole Model — parsing source files, classifying circuits and framing, running clearance and sag, emitting HITL fix proposals, and generating downstream outputs.

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

Endpoints

POST /chat

Send a user message into a conversation session and receive an SSE stream of tool calls, tool results, and assistant text.

curl -N https://hv-pole-platform-dev.web.app/api/chat \
  -H "Authorization: Bearer $VERTICAL_AI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc-123",
    "message": "Run framing analysis on this pole and walk me through the proposals."
  }'

Common SSE event types:

  • tool_call — the agent invoked a tool (e.g. run_framing_analysis)
  • tool_result — the tool returned (truncated for display)
  • assistant_delta — incremental assistant text
  • proposal — a structured HITL fix proposal with a stable ID
  • done — the turn is complete

POST /sessions

Create or update a conversation session. Sessions persist the active pole model so subsequent messages don’t re-parse.

{
  "session_id": "abc-123",
  "title": "Multi-pole project review"
}

GET /pole-model

Retrieve the active pole model for a session as JSON.

curl https://hv-pole-platform-dev.web.app/api/pole-model?session_id=abc-123 \
  -H "Authorization: Bearer $VERTICAL_AI_KEY"

POST /upload

Ingest a source file directly. Accepts SPIDA .spida, O-Calc .pplx, PLS .pol (with optional .loa), and drone / field-capture payloads. The result is a Universal Pole Model attached to the supplied session.

GET /upload-url

Returns a signed Google Cloud Storage URL for browser-side PUT uploads of large files. The signed URL expires in 15 minutes.

POST /sag-plan

Whole-line sag request with terrain. Useful when you want to drive the sag analysis directly without a chat turn.

GET /conv-poles

List the poles currently in a conversation session.

GET /esri/config

Return the ESRI feature-layer URLs and auth config for the calling tenant.

GET /download and POST /exports/{filename}

Retrieve generated SPIDA, O-Calc, PLS, USD, GeoJSON, JP Form 2 PDF, or tensor CSV outputs from a session.

Streaming details

The /chat endpoint sends SSE events as data: lines terminated by \n\n. Each event payload is a JSON object with at least a type field. Clients should:

  • Reconnect on EventStream close mid-turn (the gateway is idempotent on (session_id, turn_id))
  • Handle tool_call events for UI affordances (chips, status bars, tool log)
  • Append assistant_delta to a buffer and render incrementally
  • Treat proposal events as HITL cards — the user is expected to approve or dismiss them before the conversation continues

Errors

Errors are returned as error SSE events:

data: {"type": "error", "message": "session not found", "code": "not_found"}

For non-stream endpoints, errors are JSON with a 4xx or 5xx status code.

See also