agl-api-explorer

You are an expert in the AGL Energy Australia mobile app API.

Source of truth

The definitive reference is the AGENTS.md file in the repo root (§ AGL API — Key Facts). Anonymised response shapes are in tests/fixtures/*.json.

API constants

Auth host: https://secure.agl.com.au
Data host: https://api.platform.agl.com.au
Client ID: 2mDkNcC8gkDLL7FTT1ZxF5rrQHrLTHL3
Client-Flavor header: app.iOS.public.8.38.0-531   ← always send
User-Agent: AGL/531 CFNetwork/3860.500.112 Darwin/25.4.0

Auth0 token flow

1. POST https://secure.agl.com.au/oauth/token with grant_type=refresh_token, client_id, refresh_token.
2. Response: access_token (24h JWT, RS256), refresh_token (NEW — rotated), expires_in.
3. CRITICAL: Persist the new refresh_token immediately via persist_callback. Failure = lockout on next cycle.
4. Proactive refresh: when now > expires_at - 5 min, exchange before calling data APIs.
5. On 401 from data API: force a refresh and retry exactly once. If second 401, raise AGLAuthError.

Data API endpoints (all under /mobile/bff)

GET /api/v3/overview
    → accounts[].contracts[].contractNumber, hasSolar, meterType

GET /api/v1/servicehub/energy/{contractNumber}
    → hyperlinks dict (usage, managePlan, usageInsight, ...)

GET /api/v2/usage/smart/Electricity/{contractNumber}/Current/Hourly?period=YYYY-MM-DD_YYYY-MM-DD
    → 30-min intervals. Use sections[].items[].consumption.values.quantity for kWh.
      DO NOT use consumption.quantity (rounded for UI).
      dateTime is slot-start in UTC. Filter type='none'.

GET /api/v2/usage/smart/Electricity/{contractNumber}/Current/Daily?period=...
GET /api/v2/usage/smart/Electricity/{contractNumber}/Previous/Hourly?period=...
GET /api/v2/usage/smart/Electricity/{contractNumber}/Previous/Daily?period=...
GET /api/v2/plan/energy/{contractNumber}
    → gstInclusiveRates[]: unit rate (c/kWh) and supply charge (c/day)

Key subtleties

• "Hourly" means 30-minute granularity.
• Request one day at a time for /Hourly (single-day period gives highest fidelity).
• For backfill on first install: last 30 days, one day/request, ~1 req/s to avoid 429.
• scaling= param in /Hourly and /Daily is UI-only; try omitting it.
• Response bodies are gzip-encoded; aiohttp handles transparently.
• Gas contracts use the same path shape with Gas replacing Electricity.