API Versioning Policy
Effective: Scanii API v2.2 onward
What this means for you
We change the Scanii API in two ways: additive changes that keep your existing code working without modification, and breaking changes that ship as a new major API version your code can opt into when you're ready. Old major versions keep working; we don't sunset them on a schedule.
In practice, this means:
- Most updates ship without you doing anything. New endpoints, new optional parameters, new response fields — your code keeps running.
- When something genuinely needs to break, we publish a new major version (e.g.,
/v3/). Your code stays on its current version (/v2.2/) until you decide to upgrade. - We don't force-migrate you. The version you integrated against keeps responding correctly for as long as we run the API.
Additive changes (your code keeps working)
These ship anytime, on any version. Pin your API version (use /v2.2/files , not /files ) and your existing code is unaffected:
- New endpoints
- New optional request parameters
- New fields in responses
- New response headers
- New values in existing fields (e.g., a new finding category in
findings) - New accepted request formats (e.g.,
application/jsonaccepted alongsidemultipart/form-data) - Performance improvements
For these to be transparent to your code, your client needs to follow a few small rules — see "Writing forward-compatible code" below.
Breaking changes (require a new major version)
These ship as a new major version (/v3/ , /v4/ , etc.). Your existing integration on the previous major continues to work; you upgrade when you're ready:
- Removed or renamed fields, parameters, or endpoints
- Changed types (e.g., a number field becoming a string)
- Changed semantics of an existing field (e.g., switching from SHA-1 to SHA-256 for
checksum) - New required parameters
- Changed default behavior
Whenever possible we ship these additively first — adding checksum_sha256 alongside checksum rather than replacing it — so you can migrate gradually before the next major.
When a new major version ships, we announce it via:
- Email to API customers
- Banner on the API docs
- Entry in the changelog
- Release notes for the official SDKs
How long old versions stay supported
Old major versions remain functional indefinitely. We don't pre-commit to a sunset date. If we ever do retire a major version, you'll get at least 12 months of advance notice via email, response headers, and the changelog, plus migration support.
In practice we expect old versions to keep working for years. The /v2/ major has been stable since 2014, with v2.2 shipped in 2022.
Writing forward-compatible code
For additive changes to be invisible to your code, your client needs to handle a few things gracefully. The official Scanii SDKs do this for you. If you're building your own integration, follow these rules:
- Pin your API version explicitly. Use a versioned URL (
/v2.2/files), not the unversioned base. - Ignore unknown response fields. Don't fail if a response contains fields your code doesn't recognize — new fields will be added regularly.
- Tolerate new values in existing fields. Treat unknown finding categories or status codes as a "future value" rather than an error.
- Don't depend on field ordering or error message text. Error codes are stable; messages may be reworded.
Most JSON deserializers do the right thing by default. Common exceptions to watch for:
| Library | Setting that breaks forward-compat |
|---|---|
| Java Jackson | FAIL_ON_UNKNOWN_PROPERTIES = true |
| C# System.Text.Json | JsonUnmappedMemberHandling.Disallow |
| Go encoding/json | decoder.DisallowUnknownFields() |
| Rust serde | #[serde(deny_unknown_fields)] |
| TypeScript zod | .strict() on response schemas |
| Python pydantic | extra='forbid' |
If you're using one of these strict modes, change it to the permissive default for Scanii response types. Otherwise, additive API changes will surface as errors in your code.
Common questions
Will my code break if I do nothing? No, as long as you're pinned to an API version (e.g., /v2.2/ ) and your client follows the forward-compatibility rules above.
When should I upgrade to a new major version? When you want a feature or change that's only in the new version. There's no deadline.
What about the SDKs? The official Scanii SDKs follow the same principle — additive changes ship as minor SDK releases; breaking changes ship as new SDK majors. SDK majors typically (but not always) align with API majors.
Do I have to keep up with every new minor version? No. Stay on whatever version is working for you. Upgrade when you have a reason to.
Can I see what's changing? Yes — the changelog lists every API change, classified as additive or breaking.
Questions? Email support@uvasoftware.com.