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:

code

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.

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.

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:

code

[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 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 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 carries every tool and its current stability tier.