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

# Public Surface

> Inventory Cessy public, generated, builder, and platform-managed surfaces so integrations use the right contract.

Not every HTTP route or MCP server is a public app integration surface. Use this page to choose the right boundary.

## Public and supported

| Surface                  | Status                             | Use                                                                                                                                                                                             |
| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Generated Runtime REST   | Public generated app API           | External systems execute commands, read projections, import events, and rebuild projections when authorized.                                                                                    |
| Generated OpenAPI        | Public generated app contract      | Canonical REST contract for one published app.                                                                                                                                                  |
| GraphQL runtime API      | Public generated app API           | UI-friendly command mutations and projection queries.                                                                                                                                           |
| Runtime MCP              | Public agent integration           | Published app operation by agents.                                                                                                                                                              |
| Hosted Custom Page SDK   | Public host-provided page contract | Custom Pages import `@ces/app-sdk` for authenticated data, files, agent selection, chat, and navigation without handling tokens; the SDK contract declares each hook's runtime-source behavior. |
| Public Custom Page Share | Public no-login page surface       | External visitors open chrome-free custom pages under `/public/p/{appId}/{shareId}/...`; SDK reads and commands use the public page API as a constrained `public` principal.                    |
| Webhooks                 | Public inbound integration         | External events mapped into commands.                                                                                                                                                           |
| Subscriptions            | Public outbound integration        | Event delivery to external consumers.                                                                                                                                                           |

## Builder and identity surfaces

| Surface              | Status                     | Use                                                                    |
| -------------------- | -------------------------- | ---------------------------------------------------------------------- |
| Builder UI           | Builder app                | Human design and operation workflow.                                   |
| Design MCP read-only | Builder/agent onboarding   | App inspection, reference lookup, review, and PRD work.                |
| Design MCP full      | Trusted builder automation | Workspace edits, validation, page preview, changesets, and promotion.  |
| OAuth routes         | Public auth infrastructure | MCP OAuth discovery, consent, token, refresh, and client registration. |

## Limited support surfaces

| Surface            | Status                   | Use                                                                                                     |
| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| Adapter call route | Platform-managed support | Policy and workspace-controlled calls to configured external services. Not the normal external app API. |

## Promotion rule

If a surface is intended for external consumers, it needs a documented contract, auth story, error behavior, versioning plan, and smoke test. Otherwise keep it builder-only or platform-managed.

Public custom page shares are enabled through Workspace page metadata and become reachable only after the ChangeSet is promoted to production. Treat the generated `shareId` as a revocable bearer URL. Projection and command access still depends on explicit model `authRules`; resources without public-share authorization are not exposed through the public page API.

The Hosted Custom Page SDK and Runtime REST are different supported boundaries.
The SDK receives auth and runtime source from the page host. External frontends
and BFFs use the generated OpenAPI and Runtime REST and must not call
platform-internal Custom Page routes.