API stability

Which Algenta paths carry a compatibility promise, what changes without notice, and which paths sit outside the version scheme on purpose.

Every path this engine answers falls into exactly one of two classes. A test in the engine's own suite fails the build if a route is added that fits neither, so this page cannot quietly fall behind the code.

Class	Paths	Promise
Versioned API	/v1/*	Backward-compatible within v1. Additive change only.
Not part of the API	/mcp, /mcp/tools, /.well-known/*, /metrics, /docs, /redoc, /openapi.json, GitHub App callbacks, internal service paths	No version promise; governed by the protocol or convention that owns the path.

Sign-in (/v1/auth/*), device login (/v1/oauth/device/*), the account portal (/v1/account/*), the public price list (/v1/billing/plans) and website provider keys (/v1/byok) are part of the versioned API like everything else. Their earlier unversioned paths no longer answer.

What backward-compatible means inside v1

Within v1 these are compatible changes and ship without notice:

• a new endpoint, a new optional request field, a new response field;

• a new optional query parameter, a new enum value in a field documented as extensible;

• a new HTTP header;

• a new error code for a condition that previously produced a more general one.

These are breaking and do not happen inside v1:

• removing or renaming a path, a response field, or an error code;

• making an optional request field required, or narrowing an accepted type;

• changing the success status code, or the meaning of an existing field;

• removing an enum value.

Write clients that ignore unknown response fields and unknown headers. Match error conditions on the code string rather than on prose or on the HTTP status alone — see Error codes.

Write conflict protection

POST/PATCH/DELETE on a /v1 path single-flights byte-identical concurrent requests and honours Idempotency-Key. Four families are deliberately exempt: /v1/auth/*, /v1/oauth/device/*, /v1/account/* and /v1/byok. Two identical concurrent requests are legitimate there — a double-submitted sign-in form, or the device-code request every CLI login sends through the same sign-in portal — and single-flighting them would answer 409 resource_write_conflict instead of signing the caller in.

Because Algenta is self-hosted, you control when you upgrade

A version you have deployed does not change under you. These classes describe what a future engine version may change, not what your running deployment does.

Paths deliberately outside the version scheme

These are not oversights, and each is fixed by something other than our routing:

Path	Why it is not versioned
/mcp, /mcp/tools	The MCP endpoint URL is the value you paste into a client's configuration. MCP versions itself through the MCP-Protocol-Version header, so moving the path would break configured clients to express something the protocol already expresses. /mcp speaks Streamable HTTP only.
/.well-known/*	Fixed by RFC 8615. A client fetching /.well-known/jwks.json is following the spec.
/metrics	The Prometheus scrape convention.
/docs, /redoc, /openapi.json	Documentation surfaces for a browser, not API endpoints.
GitHub App callbacks	The receiver URL is recorded by GitHub at install time; changing it stops deliveries for existing installations.
Internal service paths	Service-to-service within one deployment, never published in the spec, no external promise.

Checking a deployment yourself

The contract is machine-readable from any running engine — you do not have to take this page's word for it:

# every published path outside /v1
curl -sS "$BASE/openapi.json" | jq -r '.paths | keys[] | select(startswith("/v1/") | not)'