Versioning & stability

When building autonomous AI agents, sudden API changes can lead to unpredictable behavior, broken workflows, and eroded trust.

At truval.dev, we recognize that API stability is the most critical feature we offer.

The /v1/ Guarantee

All truval.dev API endpoints are currently served under the /v1/ path (e.g., https://api.truval.dev/v1/email/verify).

Our promise for all /v1/ endpoints is simple: We will never introduce breaking changes.

Specifically, this means:

• Existing fields will never be removed or renamed in our JSON payloads.
• Data types of existing fields will not change (e.g., a boolean will not suddenly become a string).
• Required parameters will not be added to existing endpoints.
• The underlying logic and meaning of existing fields will remain consistent.

Additive-only changes

As the API evolves, we will make additive-only changes to /v1/. For example:

• We may add new fields to a JSON response object.
• We may add new optional parameters to a request.
• We may add new endpoints entirely.

When writing your initial OpenAPI schema interpretation or generic client code, ensure your agent ignores unrecognized JSON fields to remain forward-compatible with these additive changes.

Future versions

If we ever need to make fundamental, backwards-incompatible changes to the API structure, we will release a /v2/ API.

In that event, the /v1/ API will continue to be fully supported and maintained with a generous deprecation period (measured in years, not months) to allow ample time for migration.