Skip to content
TruthVouch Docs

API Versioning

TruthVouch uses semantic versioning for the API. Current version is v1. All endpoints are accessible via the v1 URL path.

Current Version

v1 is the current stable API version.

All endpoints:

https://api.truthvouch.com/api/v1/...
https://gateway.truthvouch.com/api/v1/...
https://trust.truthvouch.com/api/v1/...

Versioning Strategy

TruthVouch follows semantic versioning:

  • Major (v1, v2, v3) — Breaking changes
  • Minor (v1.1, v1.2) — Backward-compatible features
  • Patch (v1.0.1, v1.0.2) — Bug fixes

What Constitutes a Breaking Change

Breaking changes include:

  • Removing an endpoint
  • Removing a required response field
  • Changing response field type (e.g., string to object)
  • Changing authentication requirements
  • Changing default behavior

What Does NOT Require Major Version

Safe changes (no major version bump):

  • Adding a new endpoint
  • Adding new optional fields to responses
  • Adding new optional query parameters
  • Adding new request validation (rejecting previously accepted input may require deprecation)
  • Deprecating an endpoint (with notice period)

Deprecation Policy

Timeline

  1. Announcement — Deprecated feature announced publicly
  2. Deprecation Period — 6 months minimum before removal
  3. Sunset Date — Clear date when support ends
  4. Removal — Feature removed after sunset

Example Deprecation

2024-03-15 Announcement:

Endpoint POST /api/v1/scan is deprecated. Use POST /api/v1/governance/scan instead. Deprecation period: 6 months. Sunset date: 2024-09-15.

2024-09-16 Removal:

POST /api/v1/scan is no longer available. Use POST /api/v1/governance/scan.

Future Versions

v2 (Planned - TBD)

Planned breaking changes (not yet implemented):

  • Consolidate error codes (breaking for some clients)
  • Require pagination on all list endpoints (currently optional)
  • Change JWT refresh token expiry from 30 days to 7 days
  • Rename some response fields for consistency

No timeline yet. Will announce 6 months before v2 release.

How to Prepare for Major Version Changes

  1. Keep SDKs updated — Use the latest SDK version matching your API version
  2. Monitor changelog — Watch Changelog → for announcements
  3. Test beta releases — Use /beta endpoint to test v2 before it’s stable
  4. Set up alerts — Subscribe to deprecation notifications in dashboard

Backward Compatibility Guarantees

For v1:

  • All endpoints remain available for minimum 6 months after deprecation announcement
  • No major breaking changes to core endpoints (Governance, Shield, Compliance)
  • New fields added to responses are always optional
  • New query parameters are always optional

SDK Version Support

Each SDK version supports a specific API version:

SDK VersionAPI VersionStatus
Python 1.xv1Supported
TypeScript 1.xv1Supported
.NET 1.xv1Supported
Go 1.x (TBD)v1Planned
Java 1.x (TBD)v1Planned

SDKs will issue warnings if you’re using an SDK too far behind the latest version. Update SDKs regularly to get the latest features and security fixes.

Checking API Version

All responses include a Server header indicating the API version:

Server: TruthVouch-API/v1

Query the status endpoint for version info:

Terminal window
curl https://api.truthvouch.com/api/status \
  -H "Authorization: Bearer tv_live_..."

Response:

{
  "data": {
    "apiVersion": "1.3.0",
    "status": "operational",
    "lastMaintenance": "2024-03-10T02:00:00Z"
  }
}

Contacting Support

Have questions about versioning?

Next Steps