> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/http-api/stability.md). # 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](/http-api/errors.md). ## 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](https://www.rfc-editor.org/rfc/rfc8615.html). 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: ```bash # every published path outside /v1 curl -sS "$BASE/openapi.json" | jq -r '.paths | keys[] | select(startswith("/v1/") | not)' ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/http-api/stability.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.