# Versioning

# Versioning

Amdahl ships the platform behind a version prefix and a per-tool stability tier so you can pin your integration to exactly the level of stability you need.

## Current version

All consumer endpoints live under a single stable path:

```
https://api.amdahl.com/api/platform/v1
```

Every REST route under `/api/platform/v1/` is part of the **v1 surface**. The `v1` prefix is stable: we will not change its shape or remove routes from it without a 90-day deprecation window and a notice in the [Changelog](./changelog.md).

Breaking changes ship as a new version prefix (for example a future `/api/platform/v2/`) running side by side with v1. You opt in by updating your base URL.

## Stability tiers per tool

Individual tools inside v1 carry a stability tier. You can see the tier on each tool's reference page under [API reference: tools](./api-reference/tools/_index.md).

| Tier             | Meaning                                                             | Change policy                                                                                                     |
| ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **stable**       | Production-ready. Used by internal products and external customers. | Breaking changes get a 90-day deprecation window and a changelog entry.                                           |
| **beta**         | Feature-complete but still iterating on shape.                      | Breaking changes get a 30-day deprecation window. Opt in knowing that inputs, outputs, and error codes may shift. |
| **experimental** | Early access. Shape can change without notice.                      | No deprecation window. Pin to a specific date's behavior by cacheing responses or wrapping in your own adapter.   |

Every tool with `stability: 'beta'` or `stability: 'experimental'` carries that label in its tool description string returned by the MCP `tools/list` call and in its reference page heading. Your clients can branch on the label if you want to feature-flag beta surfaces.

## Deprecation

When we plan to remove or rename a tool, we mark it with a `deprecation` block that carries three fields:

- `since`: the version or date deprecation started.
- `replaceWith`: the replacement tool id, if one exists.
- `advisory`: a short human-readable message.

The MCP tool surface appends the advisory to the tool's description string automatically. REST callers receive the same advisory in the tool's reference page and in the OpenAPI `deprecated: true` plus `description` fields.

Example deprecation advisory:

```
[DEPRECATED since 2026-03-01] Use <replacement_tool> instead. <old_tool> will be removed on 2026-06-01.
```

Once a deprecation lands, plan to migrate before the removal date. Deprecated tools continue to work until removed; removing them is always a new version of the API.

## Breaking change policy

- **90 days minimum** notice for any breaking change to a stable tool.
- **30 days minimum** notice for any breaking change to a beta tool.
- **Changelog entry** for every deprecation and every removal, with the tool id, the replacement, and the target date.
- **Behavior change vs. shape change.** Behavior changes that preserve the input and output shape (for example, a tuning pass that makes `data.query` rank results differently) are not breaking and do not require a deprecation window. Only shape changes and removals do.

What counts as a breaking change:

- Removing a tool, route, or scope.
- Renaming a field or changing its type.
- Tightening a previously-loose validator (making an optional field required, adding a format constraint).
- Changing the meaning of an error code.

What does not count:

- Adding a new optional field to a response.
- Adding a new tool or route.
- Adding a new error code behind a condition that previously returned the same outer status.
- Loosening a validator (making a required field optional, accepting more input shapes).

## Backwards compatibility

Two specific guarantees are worth calling out because they touch existing integrations:

- **Legacy engines remain live.** The content creation engine built on `content_sessions` and the research engine built on `v3_research_history` continue to run in parallel with the new generic agent runner introduced on 2026-04-16. Existing integrations that call those routes directly keep working; we are not deprecating them on any fixed date.
- **Artifact unification preserves reads.** The artifact unification work in Q1 2026 introduced bidirectional triggers between `platform_artifacts` and the legacy `writing_samples`, `customer_posts`, `customer_testimonials`, and `style_collections` tables. Reads against either side of each pair return identical data. Writes propagate automatically. See the Changelog for details.

If you encounter a regression in a stable tool, file an issue with the correlation id from the response headers and we will roll the change back or cut a patched version.

## How to subscribe to changes

- **Changelog.** Every deprecation, new tool, and breaking change lands in [`changelog.md`](./changelog.md) first. Watch it in your repo viewer or poll it from CI if you want a signal.
- **Source of truth.** The OpenAPI spec at [`api-reference/openapi.json`](./api-reference/openapi.json) is regenerated from server code on every release. Diffing it against your pinned copy is the most reliable way to catch unannounced shape changes.
- **Tool index.** [`api-reference/tools/_index.md`](./api-reference/tools/_index.md) carries every tool and its current stability tier.

## See also

- [Changelog](./changelog.md) for the dated record of changes
- [API reference: tools](./api-reference/tools/_index.md) for stability labels
- [Rate limits](./rate-limits.md) for runtime policy that sits alongside the tool contract