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

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 loan-limit calculations. If we discover a bug producing incorrect amounts:

  • We fix it without a version bump. We do not preserve wrong amounts for the sake of API 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 correctness — no aesthetic rounding tweaks, no "cleaner" formulas.

Breaking changes ship as /v2/

  • New major version path is added; v1 keeps working.
  • Sunset announced via Sunset: <date> header on v1 responses, changelog entry, and direct customer email.

Deprecation of individual endpoints/fields within a major version

  • 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.