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:insightfor 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-Tokenand a same-hostOrigin. - CSRF: state-changing; fetch a token from
GET /auth/csrfand send it back. CSRF is enforced onPOST /api/chatand 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):
| Field | Type | Description |
|---|---|---|
messages | array | The conversation so far (role + content turns). |
agent_id | string | Which agent to talk to. Defaults to eve. |
model | string | Optional Claude model override. |
max_tokens | integer | Optional output cap. |
format | string | Output format — raw (default) or server-rendered HTML. |
chat_id | string | Optional 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:
| Path | Returns |
|---|---|
GET /api/maps/grid-intelligence/layer-config | Map 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/territories | Utility service-territory polygons |
GET /api/maps/grid-intelligence/utilities/summary | Per-utility coverage summary |
GET /api/maps/grid-intelligence/national-assets | National transmission assets |
GET /api/maps/grid-intelligence/context | Map 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 prefix | Contents |
|---|---|
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:
| Path | Purpose |
|---|---|
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}/runs | A scenario's kept runs, oldest first (chart id, run number, created time) |
GET /api/charts/export/{chart_id}.csv | CSV export of the chart series |
GET /api/charts/stats | Chart 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:
| Path | Purpose | Auth |
|---|---|---|
POST /api/reports/generate/{chat_id} | Generate a report from a conversation | authenticated |
GET /api/reports/view/{report_id} | View a generated report | authenticated; the report's chat must be yours |
GET /api/reports/download/{report_id} | Download the DOCX | authenticated; the report's chat must be yours |
Authentication and errors
- Most endpoints return
401 Unauthorizedwithout a valid session. - Grid endpoints additionally require the
insightmodule 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.