Documentation Developers

API reference

Address lookup, research runs, event streams and report downloads.

On this page

Access and conventions

These endpoints back the application; this is not a public unauthenticated research API. Research endpoints use the signed grid_owner cookie and enforce ownership. Mutations also enforce same-origin rules when an Origin header is supplied.

Examples use placeholders or request shapes, not real credentials or asserted research results. Run commands only against an environment you control. Creating a run can trigger external source requests and paid provider usage when a worker is active.

Establish a session

POST /api/session accepts a JSON token matching a configured research access credential and sets an owner cookie. Invalid credentials return 401.

curl -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"token":"<research-access-token>"}' \
  http://localhost:3000/api/session

Replace the placeholder securely; avoid recording real tokens in shared shell history. A loopback development request can also bootstrap through address lookup when local signing is configured. Keep the same cookie jar for later calls.

Find and confirm an address

GET /api/address?q=... returns { "candidates": [...] }. A candidate includes id, label and optional municipality/postcode fields. The user must select the correct result; do not assume the first result is the intended address.

curl -b cookies.txt -c cookies.txt \
  'http://localhost:3000/api/address?q=postcode%20and%20house%20number'

Queries must contain 1–300 characters. Invalid input returns 400; an upstream lookup failure returns 502.

Create research

POST /api/runs validates the request, persists input/configuration snapshots and returns 202 with a runId. This queues work; it does not synchronously return a report.

{
  "site": "<Dutch postcode>",
  "houseNumber": "<house number>",
  "confirmedAddressId": "<selected PDOK address id>",
  "proposedProject": "Battery storage for self-consumption",
  "projectType": "battery",
  "capacityKw": 5,
  "storageKwh": 10,
  "connectionSize": "unknown",
  "connectionAmperage": "3x25"
}

This illustrates assumed project inputs, not verified measurements. Allowed project types are solar, battery, ev_charging and heat_electrification. See Project inputs and the authoritative ResearchInputSchema for optional fields and bounds.

Retrieve runs and stream progress

Method and path	Behavior
`GET /api/runs/{id}`	Returns the owned run, input, saved output, events, gates and version metadata
`GET /api/runs/{id}/events`	Streams persisted research events using server-sent events
`GET /api/runs/{id}/pdf`	Downloads the owned saved report as a PDF
`POST /api/runs/{id}/cancel`	Requests cancellation of an eligible owned run
`POST /api/runs/{id}/resume`	Queues clarification for an owned run awaiting input

The stream uses event: research, JSON data and durable event IDs. Reconnect with Last-Event-ID or the after query parameter. It closes when the run becomes terminal; client disconnection is not successful completion.

curl -N -b cookies.txt \
  'http://localhost:3000/api/runs/<run-id>/events?after=0'

Clarification and cancellation

Resume accepts a required answer and optional confirmed address ID. It is valid only for a run awaiting input; it is not a general-purpose way to rewrite an old run’s project assumptions.

{
  "answer": "The selected address is correct.",
  "confirmedAddressId": "<selected PDOK address id>"
}

Cancellation is cooperative. The server marks the run cancelled and the worker propagates an abort signal when it observes the change; external work already in flight may not stop instantaneously.

Administration and map summary

Private administration endpoints include /api/admin/config, configuration publication/revert, run inspection and /api/admin/sources. They require an admin bearer credential. Publishing accepts a complete validated runtime configuration; reverting accepts a positive configuration version and appends a new version.

GET /api/grid-map exposes a read-only national summary when the source and its policy allow it. It is not property-level capacity evidence or a route to another owner’s report. Disabled, unavailable and unknown-date states must not be interpreted as zero congestion.