API lifecycle and versioning

The major API version is part of the operation path:

/v1/email-analyses

Current v1 contract

The checked-in OpenAPI document defines the exact current wire contract. Success and Problem objects use additionalProperties: false, and published enums are closed. Do not assume an unknown field or enum is valid merely because it appeared at runtime; treat it as a contract mismatch until you review an updated OpenAPI document.

Compatible documentation changes can clarify existing behavior, add examples, or improve non-contractual guidance. When a future contract explicitly permits extensibility, process only that extension point defensively.

Breaking changes

Removing or renaming a required field, changing its type or meaning, changing accepted request bytes, reinterpreting idempotency, or otherwise invalidating a conforming v1 client is a breaking change. It requires a new major version or an explicit reviewed migration path.

Adding a field or enum to today's closed schemas also requires a published contract revision and client review; this portal does not promise that strict clients can accept it silently.

Deprecation and publication

No minimum deprecation period, general-availability date, regional availability, support window, or service level is asserted here. Hermes will document a notification channel only after one is formally approved. Until then, confirm production commitments with Hermes operations.

Contract monitoring

Pin generated clients to a reviewed copy of the OpenAPI contract. Diff, review, test, and deliberately deploy every contract update.