Skip to main content

​
API Versioning

The Turris Public API uses URI-based versioning to ensure backward compatibility while allowing for continuous improvements.

​
Version Format

Include the version in your request path: 
https://public.api.live.turrisfi.com/{version}/endpoint

​
Available Versions

VersionStatusDescription
v1StableCurrent production version
v2-betaBetaNew features in testing

​
Using Versions

​
Stable Version (v1)

Use v1 for production integrations: 
curl -X GET "https://public.api.live.turrisfi.com/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Beta Version (v2-beta)

Use v2-beta to test upcoming features: 
curl -X GET "https://public.api.live.turrisfi.com/v2-beta/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"
Beta endpoints may change without notice. Do not use v2-beta in production environments.

​
Version Lifecycle

​
Stable Versions

  • Backward compatible - Existing fields and behaviors won’t change
  • Additive changes only - New optional fields may be added
  • Long-term support - Deprecated with ample notice (minimum 6 months)

​
Beta Versions

  • Subject to change - Endpoints, parameters, and responses may change
  • Early access - Try new features before general availability
  • Feedback welcome - Report issues to help us improve

​
Deprecation Policy

When a version is deprecated:
  1. Announcement - We’ll notify you via email and documentation
  2. Grace period - Minimum 6 months to migrate
  3. Sunset - Version returns 410 Gone after deprecation date

​
Deprecation Headers

Deprecated endpoints include warning headers: 
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://docs.turrisfi.com/migration>; rel="deprecation"

​
Migration Guide

When migrating between versions:
  1. Review changelog - Check what’s changed between versions
  2. Test in sandbox - Verify your integration works with the new version
  3. Update gradually - Migrate endpoint by endpoint if needed
  4. Monitor errors - Watch for issues after migration

​
Best Practices

Pin to Stable

Always use stable versions (v1) in production

Test Beta

Try beta versions in development to prepare for changes

Monitor Headers

Watch for deprecation headers in responses

Subscribe to Updates

Stay informed about version changes via our changelog