API versioning

Vaultbase’s HTTP API lives at /api/v1/.... The version path is part of the contract — every documented endpoint shape, query parameter, and response field at /api/v1/foo will continue to behave the same way for the lifetime of v1.

What v1 covers

• Every URL under /api/v1/...
• Documented request/response shapes
• HTTP status codes
• Query-parameter names and semantics
• Header names sent and recognised
• Rule expression syntax

Non-breaking changes

Land in v1 without a version bump:

• New optional fields on responses (clients should ignore unknown fields)
• New optional query parameters
• New endpoints
• New error codes (existing codes preserved)
• Performance / internal refactors that don’t change observable behavior

Breaking changes

Land in /api/v2/.... Both versions coexist for at least 12 months after v2 ships. Each legacy version’s response carries a Sunset header marking the cutoff.

Examples of changes that would be v2:

• Renaming a request/response field
• Removing an endpoint
• Tightening a default behavior (e.g. requiring an idempotency key)
• Changing an error envelope shape
• Switching a timestamp field from unix-seconds to ISO-8601

Migrating between versions

When v2 ships:

import { Vaultbase } from "@vaultbase/sdk";

const vb = new Vaultbase({ baseUrl: "https://api.example.com" });
// vb hits /api/v1/... by default

// Opt-in to v2 once you've migrated:
vb.useApiVersion("v2");

Direct REST callers update the URL prefix:

POST /api/v1/posts
POST /api/v2/posts

The Sunset: <date> header on v1 responses tells you when the deadline hits. Plan your migration before that date.

Versions

Version	Released	Status	Sunset
v1	0.7.0	current	—

What’s NOT versioned

A few endpoints sit outside the version path because they’re operational or transport-level:

Endpoint	Reason
/api/health	Pings + load-balancer checks; never changes shape
/_/health	Cluster worker probe
/_/...	Admin SPA static assets
/realtime (WebSocket)	Versioned via the WS message protocol, not URL

The /api/health endpoint will always return { data: { status: "ok" } } regardless of which API versions are in use.

Pre-1.0 notes

Vaultbase is pre-1.0 software. While the v1 path is stable within the 0.x line, the project as a whole reserves the right to ship breaking changes ahead of 1.0 — usually behind a /api/v2/... path.

When 1.0 ships, the v1 contract is locked: any breaking change requires an explicit v2 release with a 12-month deprecation window.

Custom HTTP routes

Admin-defined routes via /api/v1/custom/* are scoped to v1. Future versions will offer the same /api/v2/custom/* mount under whatever new contract surface lands.