DomainCrust API policy
DomainCrust API Versioning and Deprecation Policy
This page is the stable policy reference for agents and developers building against the DomainCrust REST API. It explains which API version is current, what changes are compatible, and how DomainCrust will communicate a future deprecation or sunset.
Current version
The current production API is v1 and is addressed with URL versioning at https://domaincrust.com/api/v1. The OpenAPI files and the API-Version: v1 response header identify this version. Clients should use the versioned URL and should not infer a version from an unversioned legacy route.
Compatibility policy
Within a major version, DomainCrust intends to keep existing paths, operation IDs, required request fields, and response meanings compatible. Additive fields, endpoints, optional query parameters, and documentation improvements may be introduced without changing the major version. Clients should ignore unknown response fields and use the documented schemas rather than depending on object key order.
A breaking change, such as removing an endpoint, changing the meaning of an existing field, or making an optional request field required, will be introduced under a new major URL version such as /api/v2. A new version will have its own OpenAPI document and migration guidance before it becomes the recommended integration target.
Deprecation and sunset signals
When a specific API version or endpoint is formally deprecated, responses will include the standardized Deprecation response field with the effective date, plus a Link field using rel="deprecation" to this policy or a more specific migration document. DomainCrust will publish the expected replacement and migration steps at the linked resource.
If a retirement date is scheduled, responses will also include the standardized Sunset HTTP-date field and a Link field using rel="sunset". Until a version is formally deprecated, the absence of Deprecation and Sunset means no retirement date has been announced. The current v1 API is not deprecated.
Client guidance
Use the JSON OpenAPI contract as the source of truth for the current endpoint surface, monitor response headers, and follow the DomainCrust developer resources page for new contracts and tooling. Questions about compatibility or a migration should be sent to api@domaincrust.com.