> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# API Versioning

> Evolve generated Cessy app contracts, platform-owned APIs, MCP tools, and docs without surprising builders or consumers.

Cessy has two kinds of contracts: generated app contracts and platform-owned contracts.

## Generated app contracts

Generated REST, GraphQL, Runtime MCP, webhooks, subscriptions, and pages change when the published DomainConfig changes.

Treat these as app-level contract changes:

* renaming commands, events, projections, or fields
* changing required fields
* removing enum values
* changing projection filters or sort fields
* changing permission expectations
* changing webhook or subscription event shape

Review generated OpenAPI and affected pages or agents before publishing breaking model changes.

## Platform-owned contracts

Platform-owned contracts include Design MCP, OAuth, Builder UI behavior, and shared documentation. Changes here need compatibility planning across all apps.

## MCP tool compatibility

For MCP tools, prefer additive changes. If a tool behavior changes, update:

* tool description
* input schema
* agent-facing reference material
* docs pages
* agent prompts or guidance that rely on it

## Docs versioning

Docs should describe the current supported platform behavior. If an app-specific generated contract differs, the generated OpenAPI for that app wins.

## Deprecation

Deprecate before removing when external consumers or agents may depend on a field, endpoint, tool, or behavior. Include replacement guidance and a migration window.