API Versioning | Cessy Builder Docs

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, admin APIs, Builder UI behavior, and docs tooling. 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
reference knowledge
docs pages
agent prompts or docs contracts 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.