API documentation is version specific and is generated from versioned YAML API definitions in the source code repository. As new versions are released, endpoint definitions may be added, modified or deprecated. We will take great care to never break the API contract, clearly communicate breaking changes and deprecations well in advance, allowing for backward compatilibity. You should be able to upgrade versions, or not, according to your needs and timeline.
Versioning follows the semantic convention of <major>.<minor>.<build>. When you call an endpoint you insert the version in the URI, (e.g. {{domain}}/v1/employees/search). When version is omitted from the URI, the latest unreleased service is being called, which may be an option to preview functionality in a staging environment.
The URI will only contain major version but the response header contains the key 'x-sh-version' in the format of major, minor, build, (e.g. 1.0.0). In future versions, this may be a helpful detail to provide to support.