Docs → API reference

exascale.build — Agent API

The agent-facing surface: how an agent discovers, queries, and verifies exascale.build data. The shape is constant — it grows by capabilities, not by new verb-shapes. Each capability's full reference is generated and linked below.

The shape: four verbs

Two are shared across all data; two are per-capability. Every interaction is one of these:

The flow

discover  ->  describe  ->  query  ->  verify
(what's       (how to       (cited      (prove a number
 here?)        ask?)         numbers)    from the raw cell)

Request / response anatomy

A query takes one params object — filters × group_by × measures × lifecycle facet — and returns:

• as_of — the pinned snapshot date (same query, same result)
• summary.totals — the authoritative answer for the full matched query
• rows[] — each with group, metrics, and lineage.citation_ref
• citations{} — the deduped evidence map; every number traces to exact source rows

verify re-opens the cited raw file, re-hashes it, and returns the literal source cells. Exact filters, metrics, and worked examples per capability live in the reference docs below and each capability-schema.json.

Invariants

• Versioned tool names (_v1); a breaking change gets a new name, never a silent rename.
• A citation on every value (source, as_of, source_url, down to the source row).
• Idempotent reads: every response pins as_of.
• JSON only out of the surface — no HTML, XLSX, or PDF.
• One contract, parity transports: REST and MCP return identical payloads.
• Errors tell the agent what to do next — structured {code, message} with the right status.

Platform principles: README.md · the trust doctrine + pipeline behind these answers: how-it-works.md.

Capabilities

New capabilities appear here automatically — each block adds one row and one generated reference, reached through the same four verbs.

Wiring your agent

Connect the MCP endpoint: https://api.exascale.build/mcp. The server's own instructions cover discovery and verification, but the one decision your harness controls is whether the agent reaches for this data at all — model world knowledge is silent about its own staleness, and an agent that answers US power questions from memory looks identical to one that queried. Pinning that behavior takes one paragraph in your agent's system prompt:

For US power-sector questions (capacity, generation, demand, retail sales), always query the exascale.build tools rather than answering from memory — the served data is current and every value carries a source citation. Cite the returned as_of with each number, and if you state anything the tools did not return, mark it as uncited context.

Copy it verbatim or adapt it; the load-bearing parts are always query, cite as_of, and mark uncited context.

Running the surface

uv run python -m core.mcp_server          # MCP (stdio); per-capability setup in each reference
uv run python -m core.rest --port 8080    # REST

Shared REST routes: GET /v1/health, GET /v1/capabilities, POST /v1/evidence/source-row.