Open app
Moonborn — Developers

API versioning policy

How Moonborn versions the API, deprecation timelines, breaking-change notice windows, and what counts as a breaking change vs additive.

Moonborn's API uses path-segment versioning: every endpoint lives under /v1/ (or /v2/ once we ship it). The version is part of the URL, so clients pin explicitly and migrations are deliberate.

Versions

  • v1 — Current. General availability. Stable contracts.
  • v2 — Not yet released. When it ships, v1 enters a deprecation window (see below).

What counts as a breaking change

Changes that require a new version:

  • Renaming a field in a response.
  • Removing a field from a response.
  • Changing a response field's type or shape.
  • Adding a new required field to a request.
  • Renaming or removing an endpoint.
  • Changing an endpoint's auth requirements (e.g. requiring a new scope).
  • Changing the meaning of an enum value already in use.

Changes that are additive (ship without a version bump):

  • Adding optional request fields with defensible defaults.
  • Adding new response fields (clients ignore unknown fields).
  • Adding new endpoints.
  • Adding new enum values to request fields (clients send what they know; new values are accepted).
  • Adding new error codes (clients should default-handle unknown codes).
  • Adding new webhook event types.
  • Adding new tier-gated features (Free clients see the existing shape; Pro/Team/Enterprise clients see new fields).

Enum additions in response fields are technically breaking — a client that exhaustively pattern-matches will fall through. We document them with a release-notes callout and migrate gradually.

Deprecation timeline

When v2 ships:

  • Day 0: v2 GA. v1 continues serving traffic.
  • Day 0 + 6 months: v1 marked deprecated. Response headers carry Deprecation: true and Sunset: <date>.
  • Day 0 + 12 months: v1 removed. Clients pinned to /v1/ get 410 Gone with a migration-pointer envelope.

Six months is the floor; for v1 specifically (the inaugural version), the deprecation window will be at least 12 months. Future version bumps follow the 6-month floor unless a security forcing function intervenes.

Reading the version

curl https://api.moonborn.co/v1/version

Returns:

{
  "apiVersion": "1.0.0",
  "buildSha": "...",
  "deployedAt": "2026-05-16T08:00:00Z"
}

The apiVersion follows semver. Major bumps are path-version changes (v1 → v2). Minor + patch bumps stay within the same path.

SDK alignment

Every SDK release is pinned to an API minor version. SDK 1.4.x speaks API 1.4.*; SDK 2.0.x speaks API 2.x. The SDK refuses to start against a path-version mismatch.

OpenAPI spec

/openapi.json always reflects the current deployed spec. Build your own clients from it; pin a snapshot in your repo if you want reproducible builds. CI keeps apps/api/openapi.json and apps/docs/public/openapi.json byte-identical.

Honest scope

We do not maintain multiple minor versions concurrently. There is no way to ask for v1.3 of the API if v1.4 has shipped — minor bumps are additive only, so v1.3 and v1.4 are wire-compatible from the client's POV.

The major version is the unit of contract. Pin to v1; migrate when the deprecation window opens; not before.

Next