Skip to main content
Kynva uses date-based versioning (same approach as Stripe, Anthropic). Each calendar release date is a frozen contract: same fields, same types, same enum values, forever.

​
How to pin a version

Send the X-API-Version header on every request: 
X-API-Version: 2026-01-01
If you don’t send the header, we default to the oldest still-supported version — currently 2026-01-01. We do this on purpose: silence is safer than guessing.

​
Supported versions

VersionStatusNotes
2026-01-01CurrentFirst public release.
When we release a new version we’ll publish:
  • A migration guide in the Changelog.
  • An automated diff highlighting renamed/removed fields.
  • An overlap window of at least 6 months before the old version is retired.

​
What can change between versions

Breaking changes (require a version bump):
  • Removing or renaming a field
  • Changing the type of a field
  • Removing or renaming an enum value
  • Changing required vs optional
  • Changing default values
  • Changing the meaning of an error code
Non-breaking changes (ship in any version):
  • Adding new fields
  • Adding new enum values
  • Adding new endpoints
  • Adding new optional headers
  • Loosening validation (e.g., accepting more formats)

​
Discover what’s available

GET https://api.kynva.ai/api/v1/facade/api-versions
Returns: 
{
  "current_version": "2026-01-01",
  "supported_versions": ["2026-01-01"],
  "default_version": "2026-01-01",
  "deprecated_versions": []
}

​
What happens if I send a bad version

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "API_VERSION_UNSUPPORTED",
    "message": "X-API-Version '2025-06-01' is not supported. See /api/v1/facade/api-versions."
  }
}
See API_VERSION_UNSUPPORTED for recovery.