Versioning

The Hyperstack API is versioned in the URL path. The current production version is v1.

https://infrahub-api.nexgencloud.com/v1/core/virtual-machines

What can change within v1

Inside an existing version, the API is additive:

• New endpoints can be added at any time.
• New optional fields can be added to request bodies and responses.
• New optional query parameters can be added to existing endpoints.
• New enum values can be added to existing fields. Treat unknown enum values as forward-compatible, handle them gracefully on the client side.
• New error codes can be added. Handle unknown error_reason values as a generic error.

The following will not change within a version:

• Existing field names, types, or removal of fields from response bodies.
• Existing required fields becoming optional or vice-versa.
• The semantics of existing endpoints, what they do and what they return.

When a new version ships

A new major version (v2, etc.) is reserved for breaking changes, field renames, removed fields, changed response shapes, or substantively-changed endpoint semantics.

When a new version ships:

• Both versions remain available simultaneously during a deprecation window.
• The current version is announced in the release notes with the deprecation timeline.
• Specific guidance for migrating endpoint by endpoint is published alongside the new version.

Building forward-compatible clients

To minimize integration cost when new versions ship:

• Pin the version in your base URL, never default to a "latest" alias.
• Ignore unknown response fields rather than rejecting them.
• Match enum values defensively, handle unrecognized values as a sensible default.
• Subscribe to release notes for advance notice of breaking changes.

Deprecation policy pending SME confirmation

The exact deprecation window and announcement cadence are being formalized. This page will be updated with the production policy once SME-confirmed.