Ctrlk
K-AI
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Schema stability policy

K-AI's two MCP servers — Retrieval and Audit — are both stable. This page describes what we commit to keep stable and what may evolve, how versions are surfaced, and what deprecation looks like.

What's stable

  • REST contracts of the underlying APIs. Paths and request/response shapes of the Retrieval API (5 operations) and the Audit API (47 operations) are stable. They follow standard semver via the OpenAPI info.version field on each spec.

  • OAuth 2.1 flow. Dynamic Client Registration (RFC 7591), Authorization Code with PKCE (S256), signed access tokens, and refresh-token rotation are stable. The discovery document, endpoint paths under /auth/oauth/, and the mcp scope name are stable.

  • Tool names and schemas for both MCP servers. All 5 Retrieval tools (retrieval_instances_list_available_instances, retrieval_documents_list, retrieval_documents_get_document, retrieval_documents_list_by_ids, retrieval_semantic_nodes_search) and all 20 Audit tools (the curated conflict-first subset of the Audit REST API) have stable names, inputs, outputs, and error semantics.

What may evolve

  • The set of operations exposed as MCP tools. New tools may be added as the curated subset grows; this is additive and never a breaking change.

  • Tool descriptions and prompts. Human-readable descriptions, parameter docs, and prompts attached to tools may be revised to improve agent ergonomics.

  • Backwards-compatible additions to response payloads. New optional fields may be added to existing tool outputs.

Versioning

  • REST APIs. Each OpenAPI spec carries a version in its info block. Semver applies: patch (bugfix), minor (additive, backwards-compatible), major (breaking).

  • MCP tools. Tool names follow the underlying operationId. A breaking change in tool inputs or outputs is reflected as a major bump on the corresponding REST spec.

  • Where to see changes.

Deprecation policy

For any breaking change to a stable surface (REST contracts, OAuth flow, MCP tool names or schemas on either server):

  • A deprecation notice is published in the relevant changelog at least 90 days before removal.

  • During the 90-day window, the deprecated tool or endpoint remains available in parallel with its replacement.

  • Removal happens in a major version bump.

PreviousCookbookNextOverview

Last updated