API Versioning
The Turris Public API uses URI-based versioning. Every request path begins with a version, and from v2 onward it also names the kind of organization you are calling as.Path format
Available versions
Both versions are stable and supported.
v2 is not a rewrite: request bodies, query parameters and response shapes are identical to v1 for every endpoint both carry, with three additive exceptions. GET /v2/auth/test-oauth also returns an orgCategory field; POST /v2/upstream/file-documents also accepts the category Surplus Lines, which v1 does not; and GET /v2/upstream/surplus-lines-filings/{filingId} shows a fileDocumentId on every checklist attachment, the policy document and every completion artifact, which GET /v1/surplus-lines-filings/{filingId} does not. Beyond those, the differences are the URL, three deprecated endpoints that v2 does not carry, and the endpoints added since v2 shipped, which exist on v2 only. See the v1 to v2 migration guide.
Personas
The persona segment identifies which kind of organization the calling credentials belong to. Your credentials determine which persona you may use. Once a persona surface ships, credentials belonging to a different persona get 403 witherrorType invalid_organization_category. A path under a persona that is not served yet is not routed at all, so it returns 404 Not Found.
v1 has no persona segment because it predates this model and serves upstream entities only. That is the reason v2 exists: without a persona in the path there is nowhere to put an agency-facing API. The agency surface is therefore v2-only, and no v1 equivalent will be added.
Four endpoints are shared across personas and carry no persona segment:
POST /v2/auth/jwt, GET /v2/auth/test-oauth, GET /v2/auth/test-restricted-access-token and GET /v2/heartbeat. The access token itself identifies your organization, so the endpoint that issues it, the two that verify it, and the health check cannot be scoped to one persona.Version lifecycle
Stable versions
- Backward compatible: existing fields and behaviours will not change
- Additive changes only: new optional fields may be added
- Long-term support: deprecated with ample notice (minimum 6 months)
One narrow exception to “additive changes only”: a field that this reference documented but that
no response has ever carried may be removed from the reference. That is a correction, not a
narrowing, because no payload changes and the property could only ever have been read as
undefined. Such a removal is announced in the changelog and tagged Breaking, so a client
generating types from the spec is told before it regenerates.Deprecation policy
When a version or an individual endpoint is deprecated:- Announcement: we notify you by email and in the documentation
- Grace period: a minimum of 6 months to migrate
- Sunset: the endpoint may stop responding after the sunset date carried in its
Sunsetheader
Deprecation headers
Deprecated endpoints include these response headers, so your integration can detect a deprecation without reading the changelog:Sunset is an HTTP date, as defined in RFC 8594. If your client logs these headers, you will see a deprecation the first time you call an affected endpoint.
Link carries two relations. rel="deprecation" points at this page. rel="successor-version" names the endpoint that replaces the one you called, so a client can report the replacement without a human reading documentation. The example above is the value returned by dangerously-invite; each deprecated endpoint names its own successor.
Three v1 endpoints currently carry these headers: the dangerously-* routes listed in the migration guide. All three are absent from v2.
Best practices
Build new integrations on v2
Same shapes as
v1, and it is where new capability landsWatch for Deprecation headers
Log them; they tell you before an announcement reaches your inbox
Test in sandbox first
https://public.api.sandbox.turrisfi.com mirrors productionSubscribe to updates
Version changes are announced in the changelog