Developers

API changelog

How API changes to the Ottili ONE Unified API are communicated — the public v1 contract, the deny-by-default boundary, deprecation registry, OpenAPI extensions, the public deprecations endpoint, and the live/beta/private-beta/planned status labels — with links to track changes early.

Überblick

The API changelog* records how the public Ottili ONE Unified API* (https://api.ottili.one/api/v1) changes over time — new endpoints, changed fields, deprecations and sunset dates. It complements the developer articles on authentication, OpenAPI downloads and product lifecycle.

The public API is the only documented, external entry point for Ottili ONE. It runs at the base URL https://api.ottili.one and is built as a deny-by-default boundary*: only the paths in the public allowlist are reachable; everything else is answered by the edge (Caddy) with 403 Forbidden.

Because the API is operated under a single major version (v1), there is no single "changelog date" for breaking changes. Instead, changes are communicated through a deprecation registry, OpenAPI extensions and a public deprecation endpoint. This article explains which API capabilities exist, what status they are in, and how you can detect changes early.

Status:* The public API v1, the deprecation registry and the deprecation endpoint are Live*.

How API changes are communicated

The Unified API uses URI path versioning*. The current major version is encoded in the path as /api/v1. There is currently no second public major version (/api/v2 is not part of the public contract). Within v1, changes are backward compatible; a breaking change gets a new path or a new major version.

Deprecated endpoints are managed through a central route inventory* (config/public_api/routes_inventory.yaml). Each route may carry deprecated, deprecated_at, sunset_at, replacement and deprecation_notes. The generated public OpenAPI document marks deprecated operations in a standards-compliant way (deprecated: true) plus Ottili-specific extensions (x-ottili-deprecated, x-ottili-replacement, x-ottili-deprecated-at, x-ottili-sunset-at).

Status labels

Every API capability carries a lifecycle label. The publicly visible labels:

Label	Meaning
`Live`	Generally available and fully supported
`Beta`	Publicly available in a pre-release state; may change
`Private Beta`	Available to an invited group
`In Development`	Actively being built; not yet available
`Planned`	Accepted and scheduled, not yet started
`Concept`	Early idea under consideration; not scheduled

(Deprecated and Disabled mark the retirement of a route or feature.) For background and the exact ordering, see [Understand feature status labels](/docs/understand-feature-status-labels).

Current API capabilities and their status

The following overview lists the publicly reachable API capabilities and their current status. All entries are verified against the deployed route inventory and the Public API service.

Capability	Route / location	Status
Public API v1 (base)	`https://api.ottili.one/api/v1`	Live
Deny-by-default public boundary (Caddy)	Edge rule, only allowlist reachable	Live
Public status endpoint	`GET /api/v1/status`	Live
Public contact endpoint	`POST /api/v1/platform/public/contact`	Live
OpenAPI downloads (aggregated + per service)	`GET /api/v1/docs/openapi/specs`, `/specs/{service_name}`, `/services`, `/validation`, `/openapi.json`, `/portal`	Live
Deprecation registry (route inventory + OpenAPI extensions)	`config/public_api/routes_inventory.yaml`	Live
Public deprecation endpoint	`GET /api/v1/public-api/deprecations`	Live

Transparency:* At this time v1 is the only public major version and has no active deprecation plans* (the internal version middleware records v1_deprecation_date: None and "v1 remains stable"). No public API capability is currently in Beta, Private Beta, In Development, Planned or Concept. These labels are reserved and will be tracked here as soon as such capabilities are published.

How to track changes

1. Query deprecations:* poll GET /api/v1/public-api/deprecations. It returns every route marked deprecated in the inventory with deprecated_at, sunset_at and replacement. If no route is marked, the state is empty.

2. Watch OpenAPI:* load the specs from /api/v1/docs/openapi and check the deprecated and x-ottili-* fields in your CI.

3. Pin to v1:* always call the /api/v1 path; do not switch versions on your own.

4. Respect status labels:* use the labels to gauge how stable a capability is.

Details on endpoints, authentication and rate limits are in the related articles.

Known limitations

Only v1 is public:* v2 is part of the internal Unified API contract but is not reachable through the public boundary.
Deprecation metadata from the inventory:* the public visibility reflects only config/public_api/routes_inventory.yaml.
No fixed minimum notice window in the contract:* the contract only enforces sunset_at >= deprecated_at.

[TypeScript SDK](/docs/typescript-sdk)
[Understand feature status labels](/docs/understand-feature-status-labels)
[Product lifecycle and feature status](/docs/product-lifecycle-and-feature-status)
[Platform and product layer](/docs/platform-layer-and-product-layer)
[What is Ottili ONE?](/docs/what-is-ottili-one)
[Getting started with Ottili ONE](/docs/getting-started-with-ottili-one)

Was this article helpful?