Varial Energy API - Developer Guide

Getting access

The developer API is currently available as a pilot for selected teams. If your team is enrolled in the pilot, you can mint API tokens yourself under Settings → API and follow the quickstart below.

If your team isn't enrolled yet, talk to us about access and we'll get you set up. The API lets you drive Varial from your own pipeline — clone a template forecast, tweak its inputs, submit it, poll for completion, and download results, all over a scoped, token-authenticated REST API.

Quickstart

The core loop: verify your token, clone a template forecast you've configured in the web UI, tweak it, submit it, poll until it completes, download the results.

1. Mint a token

Go to Settings → API, name the token, pick its access level and expiry, and copy the vrl_… string; it is shown once. Then verify it:

curl -H "Authorization: Bearer $VARIAL_TOKEN" \
  https://varialenergy.com/api/v1/me/

2. Clone a template forecast

Configure a forecast once in the web UI (demand, supply, network, everything), then clone it as many times as you need. The clone carries every input; the body is a patch applied on top:

curl -X POST -H "Authorization: Bearer $VARIAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_from": "<template-forecast-id>",
    "name": "High gas sensitivity 001",
    "scenarios": [{"name": "Central", "weather_years": [2015, 2016]}]
  }' \
  https://varialenergy.com/api/v1/forecasts/

The response is the forecast's full config document plus a validation block telling you whether it is ready to submit. The whole document is patchable through PATCH /api/v1/forecasts/{id}/.

3. Adjust demand, fuel, supply and network

Each sub-scenario's inputs are addressable on their own, so a pipeline can sweep a sensitivity without rewriting the whole document. Every one of these is a declarative replace: what you send is the complete desired set, and an entry you omit is removed.

# Lift NSW1 demand 10% in 2028. Types: demand | fuel | market-price.
curl -X PUT -H "Authorization: Bearer $VARIAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"parameter_key": "dem_di_sub", "adjustment_type": "SCALAR", "value": 1.1, "region": "NSW1", "year": 2028}]}' \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/scenarios/<sub-scenario-id>/adjustments/demand/

# Pin new-build capacity. Swap supply-overrides for network-overrides
# to retime or exclude a transmission project.
curl -X PUT -H "Authorization: Bearer $VARIAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"technology": "WIND", "region": "NSW1", "fy": "2028-29", "new_capacity": 500}]}' \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/scenarios/<sub-scenario-id>/supply-overrides/

4. Preview the cost, then submit

curl -H "Authorization: Bearer $VARIAL_TOKEN" \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/cost/

curl -X POST -H "Authorization: Bearer $VARIAL_TOKEN" \
  -H "Idempotency-Key: forecast-2026-07-11-001" \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/submit/

Submitting debits credits, so the Idempotency-Key header is required; retrying with the same key returns the original submission instead of charging twice.

5. Poll, then download

curl -H "Authorization: Bearer $VARIAL_TOKEN" \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/

curl -H "Authorization: Bearer $VARIAL_TOKEN" -o prices.csv \
  "https://varialenergy.com/api/v1/forecasts/<forecast-id>/results/?view=prices&output=csv"

Reading a forecast is how you poll it. A non-terminal forecast returns a Retry-After header with the recommended poll interval. Results return 409 forecast_not_completed until the forecast reaches completed.

6. Re-run with changes

A submitted forecast is immutable. Duplicate it for a fresh, editable draft carrying every adjustment and override — it spends no credits, so no Idempotency-Key is needed:

curl -X POST -H "Authorization: Bearer $VARIAL_TOKEN" \
  https://varialenergy.com/api/v1/forecasts/<forecast-id>/duplicate/

Authentication & scopes

Every request carries Authorization: Bearer vrl_…. Tokens expire (you'll be emailed at 14 and 3 days out) and can be revoked at any time by you or your team's admins. Tokens only work on /api/v1/; they never grant access to the web application.

A token holds a set of scopes, chosen at minting time:

Conventions

Errors. Failures return {"error": {"code", "detail"}}. Machine-readable codes include insufficient_credits (402), forecast_locked, forecast_not_draft and forecast_not_completed (409), validation_failed, idempotency_key_required, read_only_field, unknown_field (400), and throttled (429).

Pagination. List endpoints return {"data": [...], "next_cursor", "previous_cursor"}. Follow next_cursor until it is null; cursors are stable under concurrent inserts. Page size via ?page_size= (max 200).

Rate limits. Per token: 60 requests/minute burst, 1,000/hour sustained. Per team: 5,000/hour across all tokens. 429 responses carry Retry-After.

Lifecycle. A forecast reports a raw status (the exact state machine value) and a collapsed phase: draft → queued → running → completed, with waiting_capacity (transient, poll slower), failed, and cancelled. Credits are refunded automatically when a forecast fails.

Config documents. A forecast's configuration is one JSON document (schema_version: 1). PATCH follows merge semantics: keys you omit are untouched; the scenarios list, when present, is the complete desired set (existing entries matched by id/name keep their adjustors unless you send an adjustors key, which replaces that set declaratively). A submitted forecast is locked; duplicate it instead.

Versioning

The contract under /api/v1/ only changes additively: new endpoints, new optional fields. Breaking changes would ship as /api/v2/ with a long overlap. Every change is recorded in the changelog; the machine-readable spec lives at /api/v1/schema/.