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:

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:

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 400 Bad Request with unsupported-version details:

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