> 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.

# GraphQL API

> Use generated GraphQL command mutations and projection queries for Cessy custom pages and UI-oriented clients.

The GraphQL runtime surface is generated from the published DomainConfig. Use it when a UI benefits from GraphQL-shaped reads and command mutations.

## When to use GraphQL

Use GraphQL for:

* custom pages that need multiple projection reads
* UI clients that benefit from typed selection sets
* workflows where command mutations and projection queries sit close together

Use REST when an external system needs a conventional OpenAPI contract.

## Auth

GraphQL calls use the same runtime auth and permission model as REST. A caller must be authenticated and authorized for the command or projection it requests.

## Generated shape

The generated schema mirrors published commands and projections. It changes when the published DomainConfig changes, so review schema impact before publishing breaking model changes.

## Error behavior

GraphQL errors should still preserve Cessy runtime meaning: auth failures, validation failures, permission failures, command failures, projection failures, and policy-related failures need to remain distinguishable to clients.

## Agent guidance

AI builders should inspect the generated schema or Design MCP model before writing GraphQL calls. Do not invent command or projection names.