Reference
API namespaces: /api/intelligence and /api/developer/v1
Why two paths exist today, what lives in each, and the timeline for collapsing them into a single versioned surface.
The Atlas backend currently exposes two HTTP namespaces: /api/intelligence/* and /api/developer/v1/*. They share the same underlying data, the same tenant, and the same quota counters. Over the next ~6 weeks we are folding everything under /developer/v1; the old URLs will keep working via HTTP 308 redirects so nothing you build today will break.
TL;DR
Build new integrations against /api/developer/v1/*. If you are already calling /api/intelligence/*, keep doing so — those URLs will redirect to their /developer/v1 counterparts when consolidation ships. Your API key, your plan limits, and the response schemas do not change.
Today's two namespaces
/api/intelligence/*
Originally built to power the dashboards on indiaenergyatlas.com (state pages, IEX market widgets, the carbon panels). Because the data was already useful to external customers, we exposed the namespace for direct consumption. Endpoints under this prefix tend to be wider and more chart-shaped — many were designed to populate a specific UI panel rather than to be a clean machine-to-machine surface.
Examples: /api/intelligence/iex-market-data/duck-curve, /api/intelligence/carbon-summary, /api/intelligence/posoco-psp.
/api/developer/v1/*
The versioned, key-authenticated surface intended for external integrations. Every route under this prefix:
- Requires a developer API key (
X-API-Key). - Returns a stable
{ data, meta }envelope. - Honours the version contract — no breaking schema changes inside
v1. - Is metered against your plan's daily and per-minute quota.
Examples: /api/developer/v1/grid/demand/latest, /api/developer/v1/market/iex/spread, /api/developer/v1/carbon-intensity/by-state.
Quota & rate limiting
Quota is per tenant, not per namespace.
/api/intelligence/* and /api/developer/v1/* draw from the same daily-call and per-minute counters tied to your organisation. Mixing namespaces does not let you double-dip; it also does not penalise you. After consolidation lands, the namespace distinction goes away entirely and the counters stay exactly where they are.Limits are defined per plan tier (Trial / Starter / Pro / Enterprise) and documented on the Rate limits page. The X-RateLimit-Remaining response header reflects the shared counter regardless of which namespace you called.
Migration plan
Every endpoint currently served from /api/intelligence/* will be re-exposed at a canonical /api/developer/v1/* path with the same response schema. The intelligence URLs will return HTTP 308 redirects (preserving method and body) so existing clients keep working without changes.
| Phase | What ships | ETA |
|---|---|---|
| 1. Mapping freeze | Public commitment to the URL mapping table below; no schema drift in v1. | Week 1 |
| 2. Dual-mount | Every intelligence endpoint mounted at both its old and new path. Both work; new path is canonical. | Weeks 2-4 |
| 3. Redirects | Old paths switch from dual-mount to HTTP 308 -> new path. Backward-compatible. | Week 5 |
| 4. Single surface | Docs, SDKs, and OpenAPI spec drop intelligence references. Redirects stay indefinitely. | Week 6 |
We are not deprecating the intelligence URLs themselves — the redirect layer is intended to remain in place for the lifetime of v1. If we ever do retire those URLs we will publish a 12-month sunset notice first.
Endpoint mapping table
Below is the planned URL mapping. Schemas are unchanged unless flagged. "Consolidates with" marks places where two intelligence routes already returned overlapping data and will collapse into a single v1 endpoint with query parameters.
Grid (demand, frequency, power flows)
| Today | Planned /developer/v1 URL | Notes |
|---|---|---|
| GET /api/intelligence/summary | GET /developer/v1/grid/summary | All-India + zone roll-up. |
| GET /api/intelligence/states | GET /developer/v1/grid/states | State-level snapshot. |
| GET /api/intelligence/grid-frequency | GET /developer/v1/grid/frequency/latest | Already exists at v1; intelligence URL becomes a redirect. |
| GET /api/intelligence/grid-statistics | GET /developer/v1/grid/statistics | Daily aggregates. |
| GET /api/intelligence/demand-timeseries | GET /developer/v1/grid/demand/history | Consolidates with v1; adds named modes. |
| GET /api/intelligence/demand-forecast | GET /developer/v1/forecast/demand | Pro+ feature gate, identical schema. |
| GET /api/intelligence/demand-accuracy | GET /developer/v1/forecast/demand/accuracy | Forecast quality metrics. |
| GET /api/intelligence/demand-reconciliation | GET /developer/v1/grid/demand/reconciliation | SLDC vs modelled. |
| GET /api/intelligence/power-flows | GET /developer/v1/grid/power-flows | Inter-regional flows. |
| GET /api/intelligence/state-interchange-canonical | GET /developer/v1/grid/state-interchange | Canonical state-level interchange. |
| GET /api/intelligence/state-metrics-canonical | GET /developer/v1/grid/states/canonical | Canonical state metrics. |
| GET /api/intelligence/posoco-psp | GET /developer/v1/grid/psp | POSOCO Power System Performance. |
IEX market
| Today | Planned /developer/v1 URL | Notes |
|---|---|---|
| GET /api/intelligence/iex-market-data | GET /developer/v1/market/iex/latest | Already exists at v1. |
| GET /api/intelligence/iex-market-data/heatmap | GET /developer/v1/market/iex/heatmap | |
| GET /api/intelligence/iex-market-data/spread | GET /developer/v1/market/iex/spread | Already exists at v1. |
| GET /api/intelligence/iex-market-data/price-duration | GET /developer/v1/market/iex/price-duration | Already exists at v1. |
| GET /api/intelligence/iex-market-data/duck-curve | GET /developer/v1/market/iex/duck-curve | |
| GET /api/intelligence/iex-market-data/storage-arbitrage | GET /developer/v1/market/iex/storage-arbitrage | |
| GET /api/intelligence/iex-market-data/forward-curve | GET /developer/v1/forecast/iex-forward-curve | Already exists at v1; intelligence URL becomes a redirect. |
| GET /api/intelligence/iex-area-prices | GET /developer/v1/market/iex/area-prices | |
| GET /api/intelligence/iex-canonical | GET /developer/v1/market/iex/canonical | |
| GET /api/intelligence/iex-green-market | GET /developer/v1/market/iex/green | |
| GET /api/intelligence/open-access-charges | GET /developer/v1/market/open-access-charges |
Fuel mix & carbon
| Today | Planned /developer/v1 URL | Notes |
|---|---|---|
| GET /api/intelligence/carbon-intensity | GET /developer/v1/carbon-intensity/by-state | Consolidates with v1 — same data, broader query surface. |
| GET /api/intelligence/carbon-intensity/latest | GET /developer/v1/carbon-intensity/latest | Already exists at v1. |
| GET /api/intelligence/carbon-intensity-mix | GET /developer/v1/carbon-intensity/with-fuel-mix | Joined fuel-mix + CI response. |
| GET /api/intelligence/carbon-forecast | GET /developer/v1/forecast/carbon-intensity | Already exists at v1; intelligence URL becomes a redirect. |
| GET /api/intelligence/carbon-summary | GET /developer/v1/carbon-intensity/summary | Daily roll-ups. |
| GET /api/intelligence/fuel-mix-timeseries | GET /developer/v1/fuel-mix/latest | Consolidates with v1 — `state=` param replaces separate route. |
| GET /api/intelligence/canonical-freshness | GET /developer/v1/meta/canonical-freshness | Data-pipeline freshness. |
Catalog & content
| Today | Planned /developer/v1 URL | Notes |
|---|---|---|
| GET /api/intelligence/catalog | GET /developer/v1/catalog | Self-describing endpoint catalogue. |
| GET /api/intelligence/power-plants | GET /developer/v1/assets/power-plants | Plant-level register. |
| GET /api/intelligence/renewable-capacity | GET /developer/v1/assets/renewable-capacity | |
| GET /api/intelligence/daily-brief | GET /developer/v1/briefings/daily | |
| GET /api/intelligence/daily-summary | GET /developer/v1/briefings/daily-summary | |
| POST /api/intelligence/project-economics | POST /developer/v1/tools/project-economics | Computational endpoint. |
| GET /api/intelligence/jobs | GET /developer/v1/jobs | Async job status. |
Price alerts (already deprecated on intelligence)
The /api/intelligence/price-alerts/* routes were marked deprecated=True at launch and have always been mirrored under /api/alerts/*. They will move to /developer/v1/alerts/* as part of this consolidation; clients still calling the intelligence variants will continue to redirect.
FAQ
Will any of my existing /api/intelligence calls break?
No. During phase 2 both URLs serve identical responses. From phase 3 onwards the old URL returns a 308 redirect to the new URL, which most HTTP clients follow transparently. If your client refuses to follow 308s for non-GET methods, the only POST endpoint affected is /api/intelligence/project-economics; switch to /api/developer/v1/tools/project-economics at your convenience before phase 3 ships.
Will my quota usage change?
No. Quota is and always has been counted per tenant. After consolidation it is counted in exactly the same place; there is just one canonical URL feeding the counter instead of two.
Do I need a key for /api/intelligence today?
Today some intelligence endpoints accept anonymous traffic for the dashboard's benefit. Once they redirect into /developer/v1, the existing key-required contract on /developer/v1 applies. If you currently call intelligence routes anonymously and want a smooth migration, generate a key now (guide) and start sending it on every request — it's honoured today and required after phase 5.
Will any response schemas change?
No. Where an intelligence endpoint and a v1 endpoint already returned slightly different shapes (e.g. v1 wraps payloads in a { data, meta } envelope), the v1 envelope wins and the intelligence URL will start emitting it before the redirect lands so clients can adopt the envelope ahead of time. We will publish a one-week heads-up on the changelog before that flip.