> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API version differences

> What changed between v2.0, v2.1, and v2.2 — and how to migrate.

The Nectar API has three active versions. **v2.2 is recommended for all new integrations.** This guide explains the differences and how to migrate.

## Version overview

| Version  | Status      | Base URL                                  |
| -------- | ----------- | ----------------------------------------- |
| **v2.2** | Recommended | `https://external.nectarclimate.com/v2.2` |
| **v2.1** | Supported   | `https://external.nectarclimate.com/v2.1` |
| **v2.0** | Legacy      | `https://external.nectarclimate.com/v2`   |

All three versions share the same authentication (`X-API-Key` header), the same endpoints, and the same pagination format. The differences are in the **response shapes** for document and usage data serializers.

## What changed in v2.1

v2.1 updated the serializers for **documents** and **usage data** endpoints. Changes include:

* Updated document response fields with additional metadata
* Updated usage data response fields with additional detail
* All other endpoints (companies, sites, connections, meters, jobs, webhooks) are identical to v2.0

## What changed in v2.2

v2.2 updated the serializer for **documents** only. Changes include:

* Updated document response fields with enhanced data
* Usage data endpoints are identical to v2.1
* All other endpoints are identical to v2.0

## Migration path

### From v2.0 to v2.2

1. Update your base URL from `/v2` to `/v2.2`
2. Update any code that parses document responses — the response shape has changed
3. Update any code that parses usage data responses — the response shape has changed
4. Test against the [sandbox](/developer-guide/sandbox-testing) before switching production traffic

### From v2.1 to v2.2

1. Update your base URL from `/v2.1` to `/v2.2`
2. Update any code that parses document responses — the response shape has changed
3. Usage data and all other endpoints are compatible without changes
4. Test against the [sandbox](/developer-guide/sandbox-testing) before switching production traffic

## Checking your version

The `/ping` endpoint returns version information. Use it to confirm which version you're calling:

```bash theme={null}
curl -X GET 'https://external.nectarclimate.com/v2.2/ping' \
  -H 'X-API-Key: YOUR_SECRET_KEY'
```

## Running versions side by side

You can call multiple API versions simultaneously. This is useful during migration — call v2.2 for new features while maintaining v2.0 for legacy integrations. All versions read from and write to the same data.

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="square-terminal" href="/api-reference">
    Full endpoint documentation with version switcher
  </Card>

  <Card title="API getting started" icon="rocket" href="/developer-guide/getting-started">
    Authentication and first request on v2.2
  </Card>
</CardGroup>