Skip to content

Stability and versioning

This page is the canonical, customer-facing version of our API stability contract. The same text lives in the internal API spec and is mirrored here on every release.

Scope — covered

  • All /v1/* endpoints
  • JSON request/response body shapes (field names, types, nesting)
  • HTTP status codes for documented scenarios
  • Documented error codes

Scope — not covered

  • Internal endpoints (/calculate, /bulk, /leads, /print) that serve the calculator UI
  • Server software, TLS configuration, server IP addresses
  • Performance characteristics (we improve them; we don't promise specific latencies)
  • The human-readable text of error messages (codes are stable; messages may improve)

Within v1, we MAY change without notice (additive only)

  • Add new optional request fields
  • Add new response fields
  • Add new endpoints
  • Add new enum values to response fields — clients must ignore unknowns
  • Loosen request validation
  • Improve human-readable error message text

Within v1, we WILL NOT change

  • Existing field names or types
  • Required-vs-optional status of existing request fields
  • HTTP status codes for documented scenarios
  • Enum values accepted on requests
  • The set of supported endpoints (deprecation policy applies)

Calculation correctness vs. API stability

The point of this API is to produce correct §685.203(m)(1) calculations. If we discover a bug producing incorrect amounts:

  • We fix it without a version bump. We do not preserve regulatory non-compliance for byte-stability.
  • The fix is tagged in the changelog as "Calculation behavior change" with the affected scenarios.
  • Customers should treat the live API as the source of truth, not snapshot known-good outputs.

We do not change calculation behavior for any reason other than regulatory compliance — no aesthetic rounding tweaks, no "cleaner" formulas.

Breaking changes ship as /v2/

  • New major version path is added; v1 keeps working.
  • v1 is supported for at least 12 months after v2 ships. Chosen deliberately to span a full academic year so FA offices can plan migrations during summer downtime.
  • Sunset announced via Sunset: <date> header on v1 responses, changelog entry, and direct customer email.

Deprecation of individual endpoints/fields within a major version

  • Keep working for at least 12 months from announcement.
  • Responses include Deprecation: true and Sunset: <date> HTTP headers (RFC 8594).
  • Listed on a Deprecations page in the docs.

How customers learn about changes

  • The Changelog, updated every release.
  • Direct email for breaking or calculation-behavior-changing releases.
  • This site's footer shows the current info.version of the OpenAPI spec.

Spec-doc version vs. API version

  • info.version in openapi.json (e.g., 1.4.2) — bumps for every additive release.
  • URL path version (/v1/) — bumps only on breaking changes.