# Versioning

The Kordiam API uses path-based major versioning. The API also defines an optional
`API-Version` header for minor-version negotiation within the same major version.

## Major Version In The URL

All API endpoints include the major version in the URL path:

```text title="Versioned base path"
https://api.kordiam.app/api/v2/elements
```

The major version (`v2`) represents the public API generation.

## Optional `API-Version` Header

When header-based selection is enabled for your deployment, a supported version can be requested
within the same major version using the `API-Version` header. Use only versions enabled for your
client or environment:

```bash title="Request a configured version"
curl https://api.kordiam.app/api/v2/elements \
  -H "Authorization: Bearer ..." \
  -H "API-Version: <supported-version>"
```

Rules:

- The path major version and header major version must match.
- The requested header version must be in the supported version set.
- Preview minor versions can be restricted to allowlisted integrations.
- If no supported header override is applied, the request uses the path version route.

## Unsupported Or Conflicting Versions

Unsupported, invalid, or conflicting version requests return <Badge variant="muted">400 Bad Request</Badge> with
`unsupported-version` details:

```json title="400 unsupported-version"
{
  "type": "https://docs.kordiam.app/docs/errors/unsupported-version",
  "title": "Unsupported API Version",
  "status": 400,
  "detail": "API version '3.0' is not supported.",
  "requestedVersion": "3.0",
  "supportedVersions": ["2.0"]
}
```

## Best Practices

1. Treat the `/api/v{major}` path as the stable public entry point for a major API generation
2. Use `API-Version` only when you need to request a specific supported minor version
3. Keep the header and path within the same major version
4. Handle `400 unsupported-version` responses programmatically during rollout and testing