API Versioning

The EnergyCAP API uses URL-based versioning to evolve the platform while maintaining backward compatibility for existing integrations. Understanding the versioning scheme helps you choose the right endpoints and plan for upgrades.

Version Format

Every API URL includes a version segment:

https://{environment}/api/{version}/{resource}

There are two versioning styles:

Style Format Example Used for
Legacy v3 /api/v3/meter Original API endpoints
Date-based vYYYYMM /api/v202407/channel New and replacement endpoints

The date-based format (vYYYYMM) indicates the year and month the endpoint version was introduced. For example, v202407 was introduced in July 2024.

How Versioning Works

Stable endpoints stay at v3

Most existing endpoints remain at v3 indefinitely. If an endpoint doesn’t need breaking changes, its URL never changes:

# These endpoints have been stable at v3 for years
curl -X GET "https://app.energycap.com/api/v3/meter" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

curl -X GET "https://app.energycap.com/api/v3/bill" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Breaking changes get a new version

When an endpoint needs changes that would break existing integrations — like restructured request bodies, renamed fields, or changed response formats — a new date-versioned endpoint is created alongside the old one:

# Old version — still works, but deprecated
curl -X POST "https://app.energycap.com/api/v3/channel" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# New version — use this for new integrations
curl -X POST "https://app.energycap.com/api/v202101/channel" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Both versions run in parallel during the transition period.

New capabilities get a date version

Entirely new endpoints that didn’t exist in v3 are introduced with a date-based version from the start:

curl -X POST "https://app.energycap.com/api/v202104/reportDistribution" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

What Counts as a Breaking Change

A new version is created when a change would break existing callers. Examples include:

Breaking (triggers new version) Non-breaking (same version)
Removing or renaming a field Adding a new optional field
Changing a field’s data type Adding a new endpoint
Restructuring the request body Adding new filter or sort options
Changing required vs. optional fields Expanding enum values
Removing an endpoint Fixing a bug in behavior

Non-breaking changes are applied to the existing version without creating a new one. This means an endpoint may gain new optional fields or capabilities over time at the same URL.

Deprecation

When an endpoint is replaced by a newer version, the old one is marked as deprecated. Deprecated endpoints are identified in two ways:

In the documentation

A DEPRECATED badge appears next to the operation name in the API Reference.

In API responses

Every call to a deprecated endpoint returns an ECI-Deprecated response header that tells you which version and operation replaces it:

ECI-Deprecated: Use v202101 CreateChannel instead

Check for this header in your integration to detect when endpoints you depend on have been superseded.

Deprecation Timeline

Phase Duration What happens
Active Indefinite Endpoint is current and fully supported
Deprecated 3–6 months Endpoint still works but is no longer the recommended version. The replacement is available.
Removed After deprecation period Endpoint returns an error. All callers must have migrated.
Tip
Subscribe to the EnergyCAP release notes or check the API Reference regularly to stay informed about deprecations before the removal deadline.

Migration Checklist

When you see a deprecation notice:

  1. Identify the replacement — check the ECI-Deprecated response header or the API Reference for the new version
  2. Review the changes — compare the old and new request/response formats in the documentation
  3. Update your code — change the version segment in the URL and adjust your request body or response handling as needed
  4. Test in implementation — use your implementation environment to verify the new version works with your integration
  5. Deploy to production — once verified, update your production integration before the removal deadline

Tips

  • Always use the latest version of an endpoint for new integrations — check the API Reference for the current version
  • Monitor response headers for ECI-Deprecated to catch deprecations early
  • Don’t hardcode version strings deep in your code — define them as constants or configuration so they’re easy to update
  • Test version upgrades in your implementation environment before deploying to production
  • The version in the URL is independent of the EnergyCAP application version — they are not related