Apps & Surfaces
Surfaces
Explore the data types and operations available in Surfaces.
103 operations
Compile Journey XML without saving or executing steps.
analyzePortalSiteSourceQueryRead, compile and type-check a Portal site document without saving it. Returns `valid`; `diagnostics` (each with the model `path`, `message`, `severity` error or warning, and the original `sourceRange`); `projection`, the document in its model shape; `pages`, keyed by page pointer (`/pages/0`), with each page's server Lua `exports` in source order, so an editor can offer a handler for an export that has none; `components`, each site component's `security` and `events` with their inferred input and output schemas; and `locations`, source ranges by model pointer.
analyzeWorkspaceSourceQueryAnalyze Workspace XML and Lua without saving, executing handlers or querying business data. Requires Workspace authoring permission.
compileSchemaXMLQueryCompile standalone XML schema syntax into JSON Schema without persisting it; host restrictions apply when embedded.
createJourneyMutationCreate a new journey. PERSONAL is self-service; TEAM/INSTANCE require journey:write.
createJourneyFromSourceMutationCompile authoritative Journey XML and create a journey using native scope-dependent authorization.
createJourneyVersionMutationCreate a new draft version of a journey. Always mints a new version rather than amending an open draft, so several drafts may be open at once. Owner for PERSONAL, else journey:write.
createJourneyVersionFromSourceMutationCompile Journey XML into a new draft version under an existing journey, preserving prior versions.
createPortalMutationCreate a Portal. Control allocates its generated address; retrying with the same idempotencyKey returns the same Portal.
createPortalAPICredentialMutationIssue a bearer API credential for a membership. The secret is returned only in this response.
createPortalLoginTicketMutationIssue a single-use login ticket that starts a Portal browser session. The secret is returned only in this response.
createPortalMembershipMutationAdmit a PortalUser to a Portal on behalf of a customer.
createPortalSiteMutationCreate an empty site for a Portal. Publish a source version to make it servable.
createPortalSiteVersionMutationStore a new immutable source snapshot for a site. Each call creates an independent snapshot, even for identical source.
createPortalUserMutationCreate a tenant-wide PortalUser. Admit them to a Portal with createPortalMembership.
createWorkspaceMutationCreate a new workspace. PERSONAL is self-service; TEAM/INSTANCE require workspace:write.
createWorkspaceVersionMutationCreate a new draft version of a workspace. Always mints a new version rather than amending an open draft, so several drafts may be open at once. Owner for PERSONAL, else workspace:write.
createWorkspaceVersionSnapshotMutationCreate an immutable source snapshot for reviewed publication. Parent edits create another draft instead of changing this version. Uses native Workspace authorization and validation.
dataChangeEventsSubscriptionSubscribe to real-time data change events. Requires read permission on each requested resource. Task topics are the exception: a signed-in user without task:read receives the events of their own tasks only (assigned to them, claimed by them, unclaimed on their teams).
deleteJourneyMutationDelete a journey and all its versions. Owner for PERSONAL, else journey:write.
deleteJourneyVersionMutationDelete one version from a journey's authoring history. Fails when the version is the one the journey is currently published at — delete the journey itself to remove that. Owner for PERSONAL, else journey:write.
deleteJourneyVersionIfExistsMutationDelete a journey version using native authorization, succeeding when it is already absent for parent-owned cascade cleanup.
deletePortalMutationDelete a Portal with its sites, snapshots and Portal-scoped identity records. Tenant-wide PortalUsers are kept; deleting a missing Portal succeeds.
deletePortalSiteMutationDelete a site and its snapshots. Fails with CONFLICT while an audience binding still references it; deleting a missing site succeeds.
deletePortalSiteVersionMutationDelete an unpublished source snapshot. The published snapshot cannot be deleted; deleting a missing one succeeds.
deleteWorkspaceMutationDelete a workspace and all its versions. Owner for PERSONAL, else workspace:write.
deleteWorkspaceVersionMutationDelete one version from a workspace's authoring history. Fails when the version is the one the workspace is currently published at — delete the workspace itself to remove that. Owner for PERSONAL, else workspace:write.
deleteWorkspaceVersionIfExistsMutationIdempotent cleanup retaining native scope authorization and published-version protection
generateDefaultDataQueryQueryGenerate a default GraphQL data query for an event topic. Returns a query string with all scalar fields for the resource, or null if the topic has no matching query. The query uses $id as the variable for the resource ID.
getJourneyQueryFetch a single journey by ID, if the caller may see it.
getJourneyByHandleQueryFetch a journey by its stable handle (deep links / anchored launches), if the caller may see it.
getJourneyVersionQueryFetch one journey version by ID. Returns null when the journey is not visible to the caller, and when the version is still an open draft and the caller is not its author — matching what `listJourneyVersions` would show.
getMagicQueryGraphQLQueryResolves a Magic Query string to the real GraphQL operation and variables it runs, so consumers can graduate from the façade to raw GraphQL. Does not execute.
getMagicQuerySchemaQueryReturns the input JSON Schema and output introspection for a Magic Query noun, so consumers (especially LLMs) can learn its contract before calling magicQuery.
getPortalQueryRead one Portal in this tenant, or null when it does not exist.
getPortalAPICredentialQueryRead one Portal API credential's metadata, or null when it does not exist. The secret is never returned.
getPortalLoginTicketQueryRead one Portal login ticket's metadata, or null when it does not exist. The secret is never returned.
getPortalMembershipQueryRead one Portal membership, or null when it does not exist.
getPortalSiteQueryRead one Portal site, or null when it does not exist.
getPortalSiteDocumentQueryRead a site version's source as typed parts (pages, components, routes, tools, libraries, layouts, styles, assets) with the canonical `source`, or null when the version does not exist. A sibling of `getPortalSiteVersion`, so the parts never enter IaC state. Fails closed when the stored source no longer passes the current reading rules (it was saved under rules that have since changed): the error carries `extensions.code` `PORTAL_SITE_SOURCE_UNREADABLE`, and the snapshot itself is still readable with `getPortalSiteVersion`.
getPortalSiteVersionQueryRead one immutable site source snapshot, or null when it does not exist.
getPortalUserQueryRead one PortalUser, or null when it does not exist.
getWorkspaceQueryFetch a single workspace by ID, if the caller may see it.
getWorkspaceByHandleQueryFetch a workspace by its stable handle (deep links / anchored launches), if the caller may see it.
getWorkspaceSourceQueryAuthor-only XML/Lua source envelope for one Workspace version. Compiler artifacts remain internal.
getWorkspaceVersionQueryFetch one workspace version by ID. Returns null when the workspace is not visible to the caller, and when the version is still an open draft and the caller is not its author — matching what `listWorkspaceVersions` would show.
helpChapterQueryRead a chapter of the current published manual edition.
helpChaptersQueryList human-facing manual chapters from the running deployment.
iacGuidesQueryEvery authoring guide, for a tool that syncs them to a folder. Intended for `schema pull` to call once and write to disk, not for an agent to call while authoring — a file can be grepped and re-read in part, where a response arrives whole.
iacSchemaQueryThe infrastructure-only view of this schema, for declarative tooling. Contains only annotated resources and the types they reach.