Skip to main content

REST API overview

Module: insight (always on) | Role: Any member | Licence: Free+ | Auth: Session cookie or MCP OAuth 2.1

Base URL: https://eve.ev.energy | Auth: session cookie (most endpoints) | Module: insight for grid data

The platform exposes a set of HTTP endpoints alongside its two MCP surfaces. This page covers the REST endpoints; for the MCP tool surfaces see Building on Eve. Authentication is covered in API authentication.

The workspace MCP endpoint is https://eve.ev.energy/mcp. See the MCP overview.

Chat — POST /api/chat​

Send a conversation turn to Eve (or another ev.energy agent) and stream the response back as Server-Sent Events.

  • Auth: required — the signed-in session cookie, which sets the workspace context. Writes also need X-CSRF-Token and a same-host Origin.
  • CSRF: state-changing; fetch a token from GET /auth/csrf and send it back. CSRF is enforced on POST /api/chat and other cookie-authenticated writes.
  • Rate limit: chat requests are rate-limited per IP (default 10 requests/minute); over the limit returns 429. See authentication.
  • Response: text/event-stream — the reply streams incrementally. Tool calls run inside the stream.

Request body (JSON):

FieldTypeDescription
messagesarrayThe conversation so far (role + content turns).
agent_idstringWhich agent to talk to. Defaults to eve.
modelstringOptional Claude model override.
max_tokensintegerOptional output cap.
formatstringOutput format — raw (default) or server-rendered HTML.
chat_idstringOptional conversation ID for history/audit.

The streaming chat endpoint, POST /api/v1/chat/stream, takes the same body plus map_control. When it is true, Eve may stream map_action frames that ask the client's map to change. See Map action frames.

A companion GET /auth/csrf endpoint (auth-required) returns { "csrf_token": "..." } for use with the chat POST.

Grid intelligence map data — /api/maps/grid-intelligence/...​

Backing data for Eve's integrated grid map. Authenticated, rate-limited (default 60 requests/minute), and gated by the insight module. Endpoints are read-only GETs, including:

PathReturns
GET /api/maps/grid-intelligence/layer-configMap layer configuration
GET /api/maps/grid-intelligence/network/lines/{utility}Distribution lines for a utility (bbox-queryable)
GET /api/maps/grid-intelligence/substations/{utility}Substations for a utility
GET /api/maps/grid-intelligence/hexbins/{utility_id}H3 hexbin aggregations
GET /api/maps/grid-intelligence/underground-networks/{utility}Underground network segments
GET /api/maps/grid-intelligence/utilities/territoriesUtility service-territory polygons
GET /api/maps/grid-intelligence/utilities/summaryPer-utility coverage summary
GET /api/maps/grid-intelligence/national-assetsNational transmission assets
GET /api/maps/grid-intelligence/contextMap context for a location

Vector tiles for circuits are served under the same prefix as .pbf tiles (/api/maps/grid-intelligence/tiles/circuits/{utility}/{z}/{x}/{y}.pbf) with tileset metadata at .../tiles/circuits/{utility}/metadata.json.

Gridbase reference-data API — /api/gridbase/v1/...​

The structured energy-infrastructure data layer (utilities, distribution feeders, substations, EV registrations, boundaries). Authenticated and gated by the insight module. The API is versioned under /api/gridbase/v1 and grouped:

Path prefixContents
GET /api/gridbase/v1/meta/...Health, adapters, coverage (/coverage, /coverage/{country}), config, freshness
GET /api/gridbase/v1/utilities/...Utility directory and metadata
GET /api/gridbase/v1/network/...Distribution + transmission network — e.g. GET /api/gridbase/v1/network/distribution/{country}/substations, .../lines, .../summary, .../query, .../underground-networks
GET /api/gridbase/v1/ev/...EV registration data
GET /api/gridbase/v1/geo/...Geographic boundaries
GET /api/gridbase/v1/assets/...Infrastructure assets

For what each dataset contains and its sources, see the Grid infrastructure data doc.

Charts — /api/charts/...​

Charts produced by Eve's simulation and analysis tools are rendered and exported via the chart routes:

PathPurpose
GET /eve/charts/{chart_id}Rendered chart page (HTML)
GET /api/charts/data/{chart_id}Chart data (JSON: traces, layout, statistics)
GET /api/charts/scenario/{chart_id}Rendered scenario chart page (HTML)
GET /api/charts/scenario/{scenario_id}/runsA scenario's kept runs, oldest first (chart id, run number, created time)
GET /api/charts/export/{chart_id}.csvCSV export of the chart series
GET /api/charts/statsChart storage statistics

Every chart endpoint requires you to be signed in to the web app (a workspace API key is not accepted). A chart is returned only if it was made in your workspace or in one of your own chats; any other chart is reported as not found. A shared chat shows its charts to anyone with the share link.

Each scenario simulation is kept as its own chart, {scenario_id}-run-{token}, so earlier runs can be reopened and compared. The scenario id itself always loads the latest run. Runs expire like any other chart.

Reports — /api/reports/...​

VPP / simulation reports (DOCX) generated from a chat session:

PathPurposeAuth
POST /api/reports/generate/{chat_id}Generate a report from a conversationauthenticated
GET /api/reports/view/{report_id}View a generated reportauthenticated; the report's chat must be yours
GET /api/reports/download/{report_id}Download the DOCXauthenticated; the report's chat must be yours

Authentication and errors​

  • Most endpoints return 401 Unauthorized without a valid session.
  • Grid endpoints additionally require the insight module on the workspace.
  • Rate-limited endpoints return 429 Too Many Requests.

Full detail — the session, OAuth bearer tokens, scopes, and rate limits — is in API authentication.