Versioning

The Nucleus API is currently v0 — unstable.

What v0 means

We may make breaking changes to any v0 endpoint with 30 days' notice. Notice goes via:

• The changelog — published the day a deprecation lands.
• An email to every customer with an active token, sent the same day.
• A Sunset HTTP header on the affected endpoint, naming the removal date.

If you're scripting against v0, subscribe to the changelog or check GET /api/version periodically — it returns the running build.

What "breaking" means

A change is breaking if it makes a previously-valid client request fail, or if the server's response shape becomes incompatible with a previously-valid parser. Concretely:

• Removing an endpoint
• Removing a field from a response
• Renaming a field on a request or response
• Changing the type of a field (e.g. string → number)
• Changing an enum's accepted values
• Tightening validation (a field that used to accept null now requires a value)
• Changing the HTTP method or path of an endpoint

Anything else is additive: new endpoints, new optional request fields, new response fields, new enum cases. Additive changes go out without notice.

What stays stable across versions

A handful of things are committed to be stable forever:

• The error shape ({ statusCode, message, error }) — see Errors.
• The bearer-token authentication scheme.
• The id format on every resource (opaque strings; we won't switch to numerics or change collation).

If we ever need to change one of these, it gets its own major version, not a v0 deprecation.

Looking ahead to v1

v1 lands when we have:

• Real customer signal on which endpoints are load-bearing for automation.
• A stable shape for the federation events stream (currently SSE; we may move to WebSocket).
• A token-scope refactor (the current three-scope ladder is coarse).

Until then, scripting against v0 is fine — just plan for the occasional 30-day migration.

How to stay safe

• Pin the version you tested against in your code. GET /api/version returns it.
• Subscribe to the changelog so you see deprecations the day they're announced, not 28 days in.
• Don't depend on undocumented endpoints. If it's not in the reference, it's not a contract — it might disappear without notice.