> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# VERSIONING

# API Versioning Strategy

## Current State

The Rhombus API is currently **unversioned** — there is a single version of all
endpoints (`"version": "1.0"` in the OpenAPI spec). All consumers use the same
API surface at `https://api2.rhombussystems.com`.

**No versioning mechanism is needed at this time.**

## When to Introduce Versioning

Add versioned documentation when **any** of the following occur:

1. **Breaking endpoint changes** — an existing endpoint's request/response
   schema changes in a way that would break existing integrations.
2. **Endpoint removal** — a previously documented endpoint is removed from the
   API.
3. **Authentication changes** — the `x-auth-scheme` / `x-auth-apikey` header
   contract changes.
4. **Base URL migration** — the API moves from `api2.rhombussystems.com` to a
   new host.

Non-breaking additions (new endpoints, new optional fields) do **not** require
versioning.

## How to Implement (Mintlify)

Mintlify supports version-based navigation via a `versions` array in
`docs.json`. When the time comes:

### 1. Add `versions` to `docs.json`

```json theme={null}
{
  "versions": ["v2", "v1"],
  "navigation": {
    ...
  }
}
```

The first version in the array is the default. Users can switch versions via a
dropdown in the top navigation.

### 2. Organise content by version

Each version can have its own navigation structure. Shared pages (guides,
tutorials) can be reused across versions. Only version-specific API reference
pages need separate entries.

### 3. Keep a separate OpenAPI spec per version

```
api-reference/
  v1/openapi.json   ← current spec (rename)
  v2/openapi.json   ← new version
```

Update `docs.json` to point each version's API Reference to its own spec file.

### 4. Add redirects

When deprecating a version, add redirects in `docs.json`:

```json theme={null}
"redirects": [
  { "source": "/api-reference/v1/:path*", "destination": "/api-reference/v2/:path*" }
]
```

## Deprecation Policy

When a version is deprecated:

1. Add a `<Warning>` banner to the top of the deprecated version's pages.
2. Keep the deprecated version accessible for at least **6 months**.
3. Add an entry to `changelog.mdx` announcing the deprecation.
4. If both versions are served by the API, update `docs.json` to reference both spec URLs (one per version's `openapi` field).

## References

* [Mintlify Versioning Docs](https://mintlify.com/docs/settings/versioning)
* Rhombus OpenAPI spec: `https://api2.rhombussystems.com/api/openapi/public.json` (referenced live from `docs.json`)
* Changelog: `changelog.mdx`