Versioning strategy
The Limitguard API uses URL path versioning. The current stable version is /v1/. All stable API versions are accessible simultaneously, allowing you to migrate on your own schedule within the deprecation notice window.
Current stable version:
Base URL pattern:
https://api.limitguard.ai/v1/Base URL pattern:
https://api.limitguard.ai/v{N}/{endpoint}
What counts as a breaking change
| Type | Breaking? | Examples | Notice Period |
|---|---|---|---|
| Remove endpoint | Yes | Removing /v1/risk/score |
6 months |
| Remove required field | Yes | Removing trust_score from response |
6 months |
| Change field type | Yes | Changing trust_score from integer to string |
6 months |
| Change HTTP method | Yes | POST endpoint becoming GET | 6 months |
| Change authentication scheme | Yes | Removing X-API-Key support | 6 months |
| Change scoring algorithm significantly | Behavioral | Trust score distribution shift >10 points | 3 months |
| Change recommendation thresholds | Behavioral | Adjusting proceed/review boundary | 3 months |
| Add optional field to response | No | Adding geo_risk to response |
None, additive |
| Add optional request parameter | No | Adding kyb_level parameter |
None, additive |
| Bug fix that corrects wrong behavior | No | Fixing incorrect sanctions match | None, changelog entry |
| Performance improvement | No | Reducing latency, improving accuracy | None, changelog entry |
Deprecation notice periods
- Breaking changes: Minimum 6 months advance notice before removal
- Behavioral changes: Minimum 3 months advance notice
- First 12 months (until February 2027): No version deprecations. The v1 API is committed as stable through at least February 2027.
- Exception: We may withdraw an endpoint at once, without this notice, when it returns wrong results. The endpoint then answers
410 Gone, and the error reference in the documentation says why.
Notification channels
Deprecation notices are communicated through all of the following channels:
- Email: Registered API key holders receive direct email notification
- Changelog: Published at docs.limitguard.ai/changelog
- HTTP Headers: Deprecated endpoints return
DeprecationandSunsetheaders on every response (RFC 9745 and RFC 8594) - Documentation: Deprecated endpoints are marked with a deprecation notice and migration guide
Deprecation and sunset headers (RFC 9745, RFC 8594)
Once an endpoint is deprecated, every response from that endpoint includes the following headers:
HTTP/1.1 200 OK Deprecation: @1785542400 Sunset: Mon, 01 Feb 2027 00:00:00 GMT Link: <https://docs.limitguard.ai/migration/{old-version}-to-{new-version}>; rel="successor-version" Content-Type: application/json # Deprecation: when the endpoint was deprecated, as a Unix timestamp (1 August 2026) # Sunset: date the endpoint will stop responding # Link: migration guide to the successor version
We recommend configuring your HTTP client or monitoring system to alert on the presence of Deprecation or Sunset response headers.
Migration support
For every breaking change, we publish:
- A migration guide in the documentation explaining all required code changes
- A compatibility matrix showing differences between old and new versions
- A parallel running period where both old and new versions are simultaneously available
- Direct email support for Enterprise customers during migration
Version history
| Version | Status | Released | Sunset |
|---|---|---|---|
/v1/ |
Stable, current | February 2026 | Not before February 2027 |
Questions about the versioning policy or upcoming changes? Contact support@limitguard.ai or consult the changelog.
