Service API versions

The scoring service and the review-sync service each serve their HTTP API under an API major in the URL path: /v1/..., later /v2/.... The SDK chooses the version, so this page is the single place the policy is written.

Which major the SDK calls

Each semantic_evaluation major calls exactly one API major per service. Products configure only the host (base_url stays host-only, for example http://localhost:8001); ScoringServiceClient and ReviewSyncServiceClient add the major to every route.

semantic_evaluation	Scoring service	Review-sync service
2.5.0 and later 2.x	/v1	/v1

/health, /docs, /redoc and /openapi.json are unversioned. Hostnames never carry a version. Each service's /v1 routes are listed in its API reference: scoring and review sync.

A client identifies itself with User-Agent: semantic-evaluation/<version>. The services log it together with the API version, which is how a service owner sees who still calls a retiring major.

Breaking and additive changes

Change	Kind	Where it lands
New route, new optional request field, new response field, new evaluator in the catalogue	Additive	Current major
Removed or renamed route or field, a new required request field, a changed meaning or type, a narrower accepted value set	Breaking	A new major (/vN+1)

One container app per service serves every supported major. Majors differ only at the edge: each has its own request and response models, converted onto one core, so there is one evaluator catalogue and one stored format. Every pull request that touches a service diffs its OpenAPI per major against main with oasdiff, which flags a breaking change inside a major.

Support window

Only the current and the previous major are supported. A retiring major answers with:

Header	Meaning
Deprecation (RFC 9745)	The major is deprecated
Sunset (RFC 8594)	The date from which the major may be removed
Link with rel="deprecation"	The service's API reference page

The sunset date is at least 90 days after deprecation starts, is fixed when it starts, and is never moved earlier. Removal also waits until the service logs show no traffic on the major.

What a product sees

Nothing to change in code or configuration. Update semantic-evaluation within its supported range and the client calls the matching major.

• Deprecation warning. When a response carries Deprecation, the client logs one warning per client instance with the Sunset date and "Upgrade semantic-evaluation." Upgrade the SDK before that date.
• "does not serve /v1/ routes". A 404 with the route-not-found body on a /v1 path raises RuntimeError: the service is older than the SDK. There is no fallback to unversioned paths. Update the service; a local one is updated together with the SDK. For a deployed service, ask its owner.

Current state

The unversioned routes (for example /evaluators) are deprecated aliases of /v1, deprecated on 2026-11-06 and removed no earlier than 2027-02-04. semantic_evaluation 2.5.0 calls /v1; older versions call the aliases and therefore have until the sunset date to upgrade.