API versioning policy¶

The b'nerd HQ API follows a header-based, additive-only versioning policy. This page is the customer-facing contract for how we evolve the API and how we tell you when something is changing.

Version carrier¶

Send API-Version: <integer> on every request. If you omit it, the server treats the request as the latest stable major version (currently 1).

The server always echoes the resolved version in the API-Version response header so you can confirm what shape you got:

GET /cloud/servers HTTP/1.1
Host: api.bnerd.cloud
Authorization: Bearer …
API-Version: 1

HTTP/1.1 200 OK
API-Version: 1
Content-Type: application/json

When a hypothetical v2 ships:

• API-Version: 2 selects the new shape.
• API-Version: 1 keeps the v1 shape until v1 is sunset.
• Omitting the header keeps v1 (default-for-backcompat) until v1 is sunset.
• After v1 sunset, omitted or 1 returns 410 Gone with a Link: …; rel="successor-version" pointer.

Within-version compatibility (additive-only)¶

Inside a major version, these are safe changes (no deprecation required):

• Adding new endpoints.
• Adding new optional request fields.
• Adding new response fields. Consumers MUST tolerate unknown response fields.
• Adding new enum values. Consumers MUST tolerate unknown enum values.
• Loosening validation (accepting input that was previously rejected).

These are breaking (require a deprecation + new major version):

• Removing or renaming endpoints, request fields, or response fields.
• Changing field types or semantic meaning.
• Removing enum values.
• Tightening validation in ways that reject previously-valid input.
• Changing required-vs-optional on existing fields.

v1 stabilization (2026-05-30)¶

Before the public v1 launch, the API was stabilized in one final breaking change: every success response now wraps the resource in a {metadata, data} envelope, replacing the previous mix of per-resource keys and bare-JSON responses. See Response envelope for details.

No deprecation period was required because no external customers had adopted the pre-stabilization shape. From v1 launch forward, additive-only compatibility (above) applies normally.

Deprecation signal (per endpoint)¶

When an endpoint is scheduled for removal, every response from that endpoint carries three headers:

Example:

HTTP/1.1 200 OK
API-Version: 1
Deprecation: @1748908800
Sunset: Mon, 30 Nov 2026 00:00:00 GMT
Link: <https://docs.bnerd.cloud/api/foo/migration>; rel="deprecation"

Until the sunset date, the endpoint continues to serve normally. The headers are an early warning; please use them to schedule your migration.

Sunset window¶

The minimum window between a deprecation announcement and the actual removal is 6 months. If the change closes a confirmed security gap, the window may compress to a 30-day minimum, and we'll send direct customer notice (email or in-app banner) at the time we announce.

If a sunset date arrives and the endpoint is still serving, treat that as a contract bug and please report it.

What you should do¶

• Send API-Version: 1 explicitly on every request so you're insulated from the day we change the default.
• Parse the Sunset response header and surface it in your tooling (a banner, a CLI warning, a Terraform plan note). When you see one, follow the Link header to the migration guide.
• Tolerate unknown response fields and enum values. New fields/enums can appear within a version without warning.

Stability levels¶

Endpoints documented in this API reference are part of v1. Anything not documented (admin/internal routes, raw OpenStack/PowerDNS pass-through) is not part of the v1 surface and is not covered by this policy.