Apps & Surfaces

Surfaces

Explore the data types and operations available in Surfaces.

103 operations

analyzeJourneySourceQuery

Compile Journey XML without saving or executing steps.

analyzePortalSiteSourceQuery

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

analyzeWorkspaceSourceQuery

Analyze Workspace XML and Lua without saving, executing handlers or querying business data. Requires Workspace authoring permission.

compileSchemaXMLQuery

Compile standalone XML schema syntax into JSON Schema without persisting it; host restrictions apply when embedded.

createJourneyMutation

Create a new journey. PERSONAL is self-service; TEAM/INSTANCE require journey:write.

createJourneyFromSourceMutation

Compile authoritative Journey XML and create a journey using native scope-dependent authorization.

createJourneyVersionMutation

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

createJourneyVersionFromSourceMutation

Compile Journey XML into a new draft version under an existing journey, preserving prior versions.

createPortalMutation

Create a Portal. Control allocates its generated address; retrying with the same idempotencyKey returns the same Portal.

createPortalAPICredentialMutation

Issue a bearer API credential for a membership. The secret is returned only in this response.

createPortalLoginTicketMutation

Issue a single-use login ticket that starts a Portal browser session. The secret is returned only in this response.

createPortalMembershipMutation

Admit a PortalUser to a Portal on behalf of a customer.

createPortalSiteMutation

Create an empty site for a Portal. Publish a source version to make it servable.

createPortalSiteVersionMutation

Store a new immutable source snapshot for a site. Each call creates an independent snapshot, even for identical source.

createPortalUserMutation

Create a tenant-wide PortalUser. Admit them to a Portal with createPortalMembership.

createWorkspaceMutation

Create a new workspace. PERSONAL is self-service; TEAM/INSTANCE require workspace:write.

createWorkspaceVersionMutation

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

createWorkspaceVersionSnapshotMutation

Create an immutable source snapshot for reviewed publication. Parent edits create another draft instead of changing this version. Uses native Workspace authorization and validation.

dataChangeEventsSubscription

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

deleteJourneyMutation

Delete a journey and all its versions. Owner for PERSONAL, else journey:write.

deleteJourneyVersionMutation

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

deleteJourneyVersionIfExistsMutation

Delete a journey version using native authorization, succeeding when it is already absent for parent-owned cascade cleanup.

deletePortalMutation

Delete a Portal with its sites, snapshots and Portal-scoped identity records. Tenant-wide PortalUsers are kept; deleting a missing Portal succeeds.

deletePortalSiteMutation

Delete a site and its snapshots. Fails with CONFLICT while an audience binding still references it; deleting a missing site succeeds.

deletePortalSiteVersionMutation

Delete an unpublished source snapshot. The published snapshot cannot be deleted; deleting a missing one succeeds.

deleteWorkspaceMutation

Delete a workspace and all its versions. Owner for PERSONAL, else workspace:write.

deleteWorkspaceVersionMutation

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

deleteWorkspaceVersionIfExistsMutation

Idempotent cleanup retaining native scope authorization and published-version protection

generateDefaultDataQueryQuery

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

getJourneyQuery

Fetch a single journey by ID, if the caller may see it.

getJourneyByHandleQuery

Fetch a journey by its stable handle (deep links / anchored launches), if the caller may see it.

getJourneyVersionQuery

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

getMagicQueryGraphQLQuery

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

getMagicQuerySchemaQuery

Returns the input JSON Schema and output introspection for a Magic Query noun, so consumers (especially LLMs) can learn its contract before calling magicQuery.

getPortalQuery

Read one Portal in this tenant, or null when it does not exist.

getPortalAPICredentialQuery

Read one Portal API credential's metadata, or null when it does not exist. The secret is never returned.

getPortalLoginTicketQuery

Read one Portal login ticket's metadata, or null when it does not exist. The secret is never returned.

getPortalMembershipQuery

Read one Portal membership, or null when it does not exist.

getPortalSiteQuery

Read one Portal site, or null when it does not exist.

getPortalSiteDocumentQuery

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

getPortalSiteVersionQuery

Read one immutable site source snapshot, or null when it does not exist.

getPortalUserQuery

Read one PortalUser, or null when it does not exist.

getWorkspaceQuery

Fetch a single workspace by ID, if the caller may see it.

getWorkspaceByHandleQuery

Fetch a workspace by its stable handle (deep links / anchored launches), if the caller may see it.

getWorkspaceSourceQuery

Author-only XML/Lua source envelope for one Workspace version. Compiler artifacts remain internal.

getWorkspaceVersionQuery

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

helpChapterQuery

Read a chapter of the current published manual edition.

helpChaptersQuery

List human-facing manual chapters from the running deployment.

iacGuidesQuery

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

iacSchemaQuery

The infrastructure-only view of this schema, for declarative tooling. Contains only annotated resources and the types they reach.