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

# Migrating from v1 to v2

> Step-by-step guide to upgrade from API v1 to v2.

## Why Migrate

* **Standard response envelope** — consistent structure for every response
* **camelCase fields** — follows modern JSON conventions
* **ISO 8601 dates** — `YYYY-MM-DD` instead of `DD-MMM-YY`
* **Machine-readable error codes** — branch on `errorCode` instead of parsing messages
* **New coordinates endpoint** — generate charts from lat/lng without a geocoding key

## Breaking Changes

<Warning>
  The authentication header changed between v1 and v2. This is the most common migration issue.
</Warning>

| Aspect | v1 | v2 |
| - | - | - |
| **Auth header** | `HD-Api-Key: YOUR_KEY` | `Authorization: Bearer YOUR_KEY` |
| **Date format** | `DD-MMM-YY` (e.g., `15-Jan-90`) | `YYYY-MM-DD` (e.g., `1990-01-15`) |
| **Base path** | `/v1/bodygraphs` | `/v2/charts` |
| **Response** | Flat JSON object | Envelope with `data` field |
| **Field naming** | `snake_case` | `camelCase` |
| **Error handling** | HTTP status only | `errorCode` field in response body |

### Renamed Fields

| v1 (`snake_case`) | v2 (`camelCase`) |
| - | - |
| `channels_short` | `channelsShort` |
| `channels_long` | `channelsLong` |
| `incarnation_cross` | `incarnationCross` |
| `not_self_theme` | `notSelfTheme` |
| `north_node` | `northNode` |
| `south_node` | `southNode` |

### Renamed Endpoints

| v1 | v2 |
| - | - |
| `POST /v1/bodygraphs` | `POST /v2/charts` |
| `POST /v1/bodygraphs/simple` | `POST /v2/charts/simple` |
| — | `POST /v2/charts/coordinates` (new) |

## Step-by-Step Migration

### 1. Update the base URL

```diff theme={null}
- https://api.humandesignapi.nl/v1/bodygraphs
+ https://api.humandesignapi.nl/v2/charts
```

### 2. Change the authentication header

```diff theme={null}
- HD-Api-Key: YOUR_API_KEY
+ Authorization: Bearer YOUR_API_KEY
```

The `HD-Geocode-Key` header remains the same for location-based endpoints.

### 3. Update the date format

```diff theme={null}
- "birthdate": "15-Jan-90"
+ "birthdate": "1990-01-15"
```

### 4. Update response parsing

v2 wraps the chart data in a `data` field:

```diff theme={null}
- const chart = await response.json();
- console.log(chart.type);
+ const result = await response.json();
+ const chart = result.data;
+ console.log(chart.type);
```

Always check `result.success` before accessing `result.data`.

### 5. Update field names to camelCase

```diff theme={null}
- chart.channels_short
+ chart.channelsShort

- chart.incarnation_cross
+ chart.incarnationCross

- chart.not_self_theme
+ chart.notSelfTheme

- chart.activations.design.north_node
+ chart.activations.design.northNode
```

## Complete Before and After

<CodeGroup>
  ```bash v1 theme={null}
  curl -X POST https://api.humandesignapi.nl/v1/bodygraphs/simple \
    -H "Content-Type: application/json" \
    -H "HD-Api-Key: YOUR_API_KEY" \
    -H "HD-Geocode-Key: YOUR_GEOCODE_KEY" \
    -d '{
      "birthdate": "15-Jan-90",
      "birthtime": "14:30",
      "location": "Amsterdam, The Netherlands"
    }'
  ```

  ```bash v2 theme={null}
  curl -X POST https://api.humandesignapi.nl/v2/charts/simple \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "HD-Geocode-Key: YOUR_GEOCODE_KEY" \
    -d '{
      "birthdate": "1990-01-15",
      "birthtime": "14:30",
      "location": "Amsterdam, The Netherlands"
    }'
  ```
</CodeGroup>

## FAQ

### Do I need a new API key?

No. The same API key works for both v1 and v2 — only the header name changes.

### Is v1 being deprecated?

v1 remains available with no planned sunset. However, new features (like the coordinates endpoint) are v2 only.

### Can I use v1 and v2 simultaneously?

Yes. Both versions share the same API key and credit pool. You can migrate endpoints incrementally.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.