picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/workspace.md

@@ -6,24 +6,29 @@ generated: true
 
 # Workspace schema
 
-The operations and types that `workspace.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `workspace`
 
-Get a specific workspace. Requires authentication.
+Reads a workspace.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-workspace(id: ID!, projectId: ID!): Workspace @auth
+workspace(
+  id: ID!
+  """Ignored. The workspace's ID identifies its project."""
+  projectId: ID!
+): Workspace @auth
 ```
 
 ### `workspaceExport`
 
-Export a workspace and every entity in it as a portable JSON bundle, with a
-manifest of the asset versions its content references. The asset bytes are
-not included; download each from its `downloadUrl`. Requires scope:
-`ORGANIZATION_PROJECTS_READ` on the workspace's project.
+Exports a workspace and every entity in it as a JSON bundle that `workspaceImport` reads. The
+bundle lists the asset versions its content references; download each file from its
+`downloadUrl`.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 workspaceExport(input: WorkspaceExportInput!): WorkspaceExportPayload! @auth
@@ -33,7 +38,9 @@ workspaceExport(input: WorkspaceExportInput!): WorkspaceExportPayload! @auth
 
 ### `workspacePublish`
 
-Publish a workspace, creating an immutable version snapshot. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Publishes a workspace: makes an immutable version of it and serves that version to visitors. The
+workspace becomes `LIVE`, and an archived workspace returns to the default list.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspacePublish(input: WorkspacePublishInput!): WorkspacePublishPayload! @auth
@@ -41,17 +48,10 @@ workspacePublish(input: WorkspacePublishInput!): WorkspacePublishPayload! @auth
 
 ### `workspaceVersionPublish`
 
-Promote a previously-published `WorkspaceVersion` to be its project's served
-(live) version by pointing `projects.live_workspace_version_id`
-at it and stamping the owning workspace's `publishedAt` with that version's
-original publish timestamp. Works for the latest version (re-publish) or an
-earlier one (rollback, in product terms). No new `WorkspaceVersion` row is
-appended. The target workspace becomes the project's live one (an archived
-workspace is un-archived). The draft state is NOT modified, so if the draft
-differs from the published snapshot it shows up as "unpublished changes" in
-the UI. Use `workspaceDiff` with `(baseWorkspaceId, compareWorkspaceVersionId)`
-to preview the impact before invoking this mutation. Requires scope:
-`ORGANIZATION_PROJECTS_UPDATE`.
+Makes a published version the version its project serves. No new version is made and the
+workspace's draft does not change; the workspace becomes `LIVE`, and an archived one returns to
+the default list.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceVersionPublish(input: WorkspaceVersionPublishInput!): WorkspaceVersionPublishPayload! @auth
@@ -59,7 +59,8 @@ workspaceVersionPublish(input: WorkspaceVersionPublishInput!): WorkspaceVersionP
 
 ### `workspaceCreate`
 
-Create a new workspace on a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates an empty draft workspace in a project.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceCreate(input: WorkspaceCreateInput!): WorkspaceCreatePayload! @auth
@@ -67,7 +68,8 @@ workspaceCreate(input: WorkspaceCreateInput!): WorkspaceCreatePayload! @auth
 
 ### `workspaceUpdate`
 
-Rename an existing workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Renames a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceUpdate(input: WorkspaceUpdateInput!): WorkspaceUpdatePayload! @auth
@@ -75,7 +77,9 @@ workspaceUpdate(input: WorkspaceUpdateInput!): WorkspaceUpdatePayload! @auth
 
 ### `workspaceDuplicate`
 
-Duplicate an existing workspace with all of its child entities, including its workflows. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Copies a workspace and every entity in it, workflows included, into a new draft workspace in the
+same project.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceDuplicate(input: WorkspaceDuplicateInput!): WorkspaceDuplicatePayload! @auth
@@ -83,9 +87,10 @@ workspaceDuplicate(input: WorkspaceDuplicateInput!): WorkspaceDuplicatePayload!
 
 ### `workspaceImport`
 
-Create a new draft workspace in a project from a bundle returned by
-`workspaceExport`, committing every entity in one transaction. Requires
-scope: `ORGANIZATION_PROJECTS_UPDATE` on the target project.
+Creates a draft workspace in a project from a bundle that `workspaceExport` returned. Every entity
+gets a new ID, and every reference between entities, assets through `assetMap` included, points at
+the new IDs. Nothing is created when a `userError` is returned.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceImport(input: WorkspaceImportInput!): WorkspaceImportPayload! @auth
@@ -93,7 +98,9 @@ workspaceImport(input: WorkspaceImportInput!): WorkspaceImportPayload! @auth
 
 ### `workspaceArchive`
 
-Archive a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Archives a workspace, which moves it out of the default list. It stays editable. Archiving an
+archived workspace changes nothing.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceArchive(input: WorkspaceArchiveInput!): WorkspaceArchivePayload! @auth
@@ -101,7 +108,8 @@ workspaceArchive(input: WorkspaceArchiveInput!): WorkspaceArchivePayload! @auth
 
 ### `workspaceUnarchive`
 
-Unarchive an archived workspace (restores it to `DRAFT`). Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Unarchives a workspace, which returns it to `DRAFT`.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceUnarchive(input: WorkspaceUnarchiveInput!): WorkspaceUnarchivePayload! @auth
@@ -109,7 +117,8 @@ workspaceUnarchive(input: WorkspaceUnarchiveInput!): WorkspaceUnarchivePayload!
 
 ### `workspaceDelete`
 
-Soft-delete a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a workspace that is not live.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workspaceDelete(input: WorkspaceDeleteInput!): WorkspaceDeletePayload! @auth
@@ -121,26 +130,17 @@ workspaceDelete(input: WorkspaceDeleteInput!): WorkspaceDeletePayload! @auth
 
 ```graphql
 """
-Lifecycle status of a workspace.
-
-`DRAFT` is the editable starting state. `ARCHIVED` is a read-only audit state;
-archived workspaces can be unarchived back to `DRAFT`. `LIVE` is derived, not a
-stored state: a workspace is `LIVE` when it owns the project's served version
-(set by publishing). A live workspace cannot be archived or deleted; make a
-different workspace live first. `HIDDEN` marks the per-publish snapshot copies
-that back Publish History's Restore action: excluded from `Project.workspaces`,
-reachable only via `WorkspaceVersion.snapshotWorkspace`, and flipped to `DRAFT`
-when published.
+Where a workspace is in its lifecycle. A live workspace cannot be archived or deleted.
 """
 enum WorkspaceStatus {
-  """Workspace is in draft mode: editable, not yet served by SDKs."""
+  """Editable, and not served to visitors."""
   DRAFT
-  """Workspace owns the project's served version (derived, not stored)."""
+  """Published, and owner of the version the project serves."""
   LIVE
-  """Workspace has been archived: read-only audit state."""
+  """Out of the default list. `workspaceUnarchive` returns it to `DRAFT`."""
   ARCHIVED
   """
-  Per-publish snapshot copy: excluded from workspace listings, reachable via `WorkspaceVersion.snapshotWorkspace`.
+  The copy a publish makes, read through `WorkspaceVersion.snapshotWorkspace` and left out of workspace lists.
   """
   HIDDEN
 }
@@ -150,78 +150,64 @@ enum WorkspaceStatus {
 
 ```graphql
 """
-A workspace — a versioned container of features, experiences, conditions,
-actions, steps, fields, and CMS content for one project.
-
-Lifecycle: `DRAFT` → `LIVE` (via `workspacePublish`) → `ARCHIVED` (via
-`workspaceArchive`). At most one workspace per project may be `LIVE`.
-Publishing creates an immutable `WorkspaceVersion` snapshot; use
-`workspaceDiff` to preview changes before publishing.
-
-The connection fields (`conditions`, `steps`, `fields`, etc.) page over
-this workspace's draft state; the previously-published version is
-exposed via `latestVersion` and read through `workspaceDiff`.
+One version of a project's configuration: its experiences, feature flags, steps, fields, actions,
+conditions, workflows and content. Its connection fields read its current content; publishing it
+makes an immutable `WorkspaceVersion`.
 """
 type Workspace {
-  """Unique workspace identifier."""
+  """The ID of the workspace."""
   id: ID!
-  """User-facing display name."""
+  """The workspace's name."""
   name: String!
-  """Current status of the workspace."""
+  """Where the workspace is in its lifecycle."""
   status: WorkspaceStatus!
-  """The project this workspace belongs to."""
+  """The project the workspace belongs to."""
   project: Project!
-  """The project ID this workspace belongs to."""
+  """The ID of the project the workspace belongs to."""
   projectId: ID!
-  """Conditions within this workspace."""
+  """The workspace's conditions."""
   conditions(first: Int, after: String, last: Int, before: String): ConditionConnection!
-  """Steps within this workspace."""
+  """The workspace's steps."""
   steps(first: Int, after: String, last: Int, before: String): StepConnection!
-  """Fields within this workspace."""
+  """The workspace's fields."""
   fields(first: Int, after: String, last: Int, before: String): FieldConnection!
-  """Actions within this workspace."""
+  """The workspace's actions."""
   actions(first: Int, after: String, last: Int, before: String): ActionConnection!
-  """Features within this workspace."""
+  """The workspace's feature flags."""
   features(first: Int, after: String, last: Int, before: String): FeatureConnection!
-  """
-  Experiences within this workspace, optionally filtered by type (`FLOW` / `PAGE`).
-  """
+  """The workspace's experiences, of one type when `type` is set."""
   experiences(type: ExperienceType, first: Int, after: String, last: Int, before: String): ExperienceConnection!
-  """Workflows within this workspace."""
+  """The workspace's workflows. `last` and `before` are ignored."""
   workflows(first: Int, after: String, last: Int, before: String): WorkflowConnection!
   """
-  CMS Content Models within this workspace, optionally filtered by category.
+  The workspace's Content Models, of one category when `category` is set.
   """
   contentModels(category: ContentModelCategory, first: Int, after: String, last: Int, before: String): ContentModelConnection!
   """
-  CMS Content Blocks within this workspace, optionally filtered by category.
+  The workspace's Content Blocks, of one category when `category` is set.
   """
   contentBlocks(category: ContentBlockCategory, first: Int, after: String, last: Int, before: String): ContentBlockConnection!
   """
-  CMS Content Entries within this workspace, optionally filtered by parent Content Model.
+  The workspace's content entries, of one Content Model when `contentModelId` is set.
   """
   contentEntries(contentModelId: ID, first: Int, after: String, last: Int, before: String): ContentEntryConnection!
-  """Preview token for previewing unpublished workspace changes in the SDK."""
+  """
+  The preview token that lets a Delivery API request read the workspace's unpublished content.
+  """
   previewToken: String!
-  """When this workspace was created."""
+  """When the workspace was created."""
   createdAt: DateTime!
-  """When this workspace was last published (null if never published)."""
-  publishedAt: DateTime
   """
-  When the workspace draft content was last modified (entity create/update/delete).
+  When the version the workspace last made live was published. Null when it has never been published.
   """
+  publishedAt: DateTime
+  """When an entity in the workspace was last created, changed or deleted."""
   draftChangedAt: DateTime!
   """
-  The most recent published snapshot for this workspace, or null if it
-  has never been published. Snapshot contents are only readable via
-  `workspaceDiff`.
+  The workspace's most recent version. Null when it has never been published.
   """
   latestVersion: WorkspaceVersion
-  """
-  Published version history for this workspace, ordered newest-first.
-  Supports forward (`first`/`after`) and backward (`last`/`before`)
-  pagination with stable cursors over `(publishedAt, id)`.
-  """
+  """The workspace's versions, newest first."""
   versions(first: Int, after: String, last: Int, before: String): WorkspaceVersionConnection!
 }
 ```
@@ -229,11 +215,11 @@ type Workspace {
 ### `WorkspaceEdge`
 
 ```graphql
-"""Edge type for `WorkspaceConnection`."""
+"""A workspace in a page of results."""
 type WorkspaceEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The workspace."""
+  """The item."""
   node: Workspace!
 }
 ```
@@ -241,13 +227,13 @@ type WorkspaceEdge {
 ### `WorkspaceConnection`
 
 ```graphql
-"""Relay-style connection of workspaces."""
+"""A page of workspaces."""
 type WorkspaceConnection {
-  """List of workspace edges."""
+  """The edges in this page."""
   edges: [WorkspaceEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of workspaces."""
+  """The number of items across all pages."""
   totalCount: Int!
 }
 ```
@@ -255,15 +241,11 @@ type WorkspaceConnection {
 ### `WorkspacePublishInput`
 
 ```graphql
-"""Input for `workspacePublish` — promote a draft workspace to live."""
+"""The input of `workspacePublish`."""
 input WorkspacePublishInput {
-  """
-  Project ID. Derived from `workspaceId`; kept for backwards compatibility.
-  """
+  """Ignored. The workspace identifies its project."""
   projectId: ID @deprecated(reason: "Derived from workspace; no longer required.")
-  """
-  Workspace ID to publish. Must currently be in `DRAFT` or `LIVE` status (publishing a live workspace is a no-op rejection).
-  """
+  """The ID of the workspace to publish."""
   workspaceId: ID!
 }
 ```
@@ -271,13 +253,13 @@ input WorkspacePublishInput {
 ### `WorkspacePublishPayload`
 
 ```graphql
-"""Payload returned by `workspacePublish`."""
+"""The result of `workspacePublish`."""
 type WorkspacePublishPayload {
-  """The published workspace, now in `LIVE` status."""
-  workspace: Workspace
   """
-  Validation errors encountered during publish. Empty array indicates success.
+  The published workspace, now `LIVE`. Null when a `userError` was returned.
   """
+  workspace: Workspace
+  """The problems that stopped the publish. Empty on success."""
   userErrors: [WorkspacePublishUserError!]!
 }
 ```
@@ -285,13 +267,11 @@ type WorkspacePublishPayload {
 ### `WorkspacePublishErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspacePublish`."""
+"""Why `workspacePublish` failed."""
 enum WorkspacePublishErrorCode {
-  """The target workspace does not exist."""
+  """The workspace or its project does not exist."""
   WORKSPACE_NOT_FOUND
-  """
-  The target workspace is already live; publishing a live workspace is not allowed.
-  """
+  """The workspace is live and has no unpublished changes."""
   WORKSPACE_ALREADY_LIVE
 }
 ```
@@ -299,13 +279,15 @@ enum WorkspacePublishErrorCode {
 ### `WorkspacePublishUserError`
 
 ```graphql
-"""User-facing error for `workspacePublish`."""
+"""A problem that stopped `workspacePublish`."""
 type WorkspacePublishUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspacePublishErrorCode!
 }
 ```
@@ -313,20 +295,9 @@ type WorkspacePublishUserError {
 ### `WorkspaceVersionPublishInput`
 
 ```graphql
-"""
-Input for `workspaceVersionPublish`. Promotes a previously-published
-`WorkspaceVersion` to be its project's served (live) version. The target may
-be the most recent version (a straight re-publish) or an earlier one (a
-rollback, in product terms).
-
-The version is the sole identifier: its owning workspace and project are
-resolved from it. Publishing makes that workspace the project's live one,
-un-archiving it if it was archived.
-"""
+"""The input of `workspaceVersionPublish`."""
 input WorkspaceVersionPublishInput {
-  """
-  A previously-published `WorkspaceVersion` to make its project's served version.
-  """
+  """The ID of the version to serve."""
   workspaceVersionId: ID!
 }
 ```
@@ -334,22 +305,13 @@ input WorkspaceVersionPublishInput {
 ### `WorkspaceVersionPublishPayload`
 
 ```graphql
-"""
-Payload returned by `workspaceVersionPublish`. On success, `workspace` is the
-workspace that now owns the project's served version:
-`projects.live_workspace_version_id` points at the target version and the
-workspace's `publishedAt` is stamped with that version's original publish
-timestamp (the workspace is un-archived if it was archived). No new
-`WorkspaceVersion` row is created and the draft state is NOT modified.
-"""
+"""The result of `workspaceVersionPublish`."""
 type WorkspaceVersionPublishPayload {
   """
-  The workspace now serving the published version, or null if a `userError` was returned.
+  The workspace that owns the version, now `LIVE`. Null when a `userError` was returned.
   """
   workspace: Workspace
-  """
-  Validation errors encountered while publishing the version. Empty array indicates success.
-  """
+  """The problems that stopped the publish. Empty on success."""
   userErrors: [WorkspaceVersionPublishUserError!]!
 }
 ```
@@ -357,15 +319,13 @@ type WorkspaceVersionPublishPayload {
 ### `WorkspaceVersionPublishErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceVersionPublish`."""
+"""Why `workspaceVersionPublish` failed."""
 enum WorkspaceVersionPublishErrorCode {
-  """The version's owning workspace no longer exists (e.g. it was deleted)."""
+  """The workspace the version was published from has been deleted."""
   WORKSPACE_NOT_FOUND
-  """The target `workspaceVersionId` does not exist."""
+  """The version does not exist."""
   WORKSPACE_VERSION_NOT_FOUND
-  """
-  The target `workspaceVersionId` is already the project's served version; publishing it again would be a no-op.
-  """
+  """The project already serves the version."""
   WORKSPACE_VERSION_ALREADY_LIVE
 }
 ```
@@ -373,13 +333,15 @@ enum WorkspaceVersionPublishErrorCode {
 ### `WorkspaceVersionPublishUserError`
 
 ```graphql
-"""User-facing error for `workspaceVersionPublish`."""
+"""A problem that stopped `workspaceVersionPublish`."""
 type WorkspaceVersionPublishUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceVersionPublishErrorCode!
 }
 ```
@@ -387,11 +349,11 @@ type WorkspaceVersionPublishUserError {
 ### `WorkspaceCreateInput`
 
 ```graphql
-"""Input for `workspaceCreate`."""
+"""The input of `workspaceCreate`."""
 input WorkspaceCreateInput {
-  """Project to create the workspace in."""
+  """The ID of the project to create the workspace in."""
   projectId: ID!
-  """User-facing display name for the new workspace."""
+  """The workspace's name. Leading and trailing spaces are trimmed."""
   name: String!
 }
 ```
@@ -399,11 +361,11 @@ input WorkspaceCreateInput {
 ### `WorkspaceCreatePayload`
 
 ```graphql
-"""Payload returned by `workspaceCreate`."""
+"""The result of `workspaceCreate`."""
 type WorkspaceCreatePayload {
-  """The newly created workspace (in `DRAFT` status)."""
+  """The new workspace, in `DRAFT`. Null when a `userError` was returned."""
   workspace: Workspace
-  """Validation errors encountered while creating the workspace."""
+  """The problems that stopped the create. Empty on success."""
   userErrors: [WorkspaceCreateUserError!]!
 }
 ```
@@ -411,11 +373,11 @@ type WorkspaceCreatePayload {
 ### `WorkspaceCreateErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceCreate`."""
+"""Why `workspaceCreate` failed."""
 enum WorkspaceCreateErrorCode {
-  """The provided name was empty."""
+  """The name is blank."""
   NAME_REQUIRED
-  """The target project does not exist."""
+  """The project does not exist."""
   PROJECT_NOT_FOUND
 }
 ```
@@ -423,13 +385,15 @@ enum WorkspaceCreateErrorCode {
 ### `WorkspaceCreateUserError`
 
 ```graphql
-"""User-facing error for `workspaceCreate`."""
+"""A problem that stopped `workspaceCreate`."""
 type WorkspaceCreateUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceCreateErrorCode!
 }
 ```
@@ -437,11 +401,11 @@ type WorkspaceCreateUserError {
 ### `WorkspaceUpdateInput`
 
 ```graphql
-"""Input for `workspaceUpdate` — only the display name is mutable."""
+"""The input of `workspaceUpdate`. Every field is required."""
 input WorkspaceUpdateInput {
-  """Workspace to rename."""
+  """The ID of the workspace to rename."""
   workspaceId: ID!
-  """New display name."""
+  """The workspace's new name. Leading and trailing spaces are trimmed."""
   name: String!
 }
 ```
@@ -449,11 +413,11 @@ input WorkspaceUpdateInput {
 ### `WorkspaceUpdatePayload`
 
 ```graphql
-"""Payload returned by `workspaceUpdate`."""
+"""The result of `workspaceUpdate`."""
 type WorkspaceUpdatePayload {
-  """The updated workspace."""
+  """The updated workspace. Null when a `userError` was returned."""
   workspace: Workspace
-  """Validation errors encountered while updating the workspace."""
+  """The problems that stopped the update. Empty on success."""
   userErrors: [WorkspaceUpdateUserError!]!
 }
 ```
@@ -461,11 +425,11 @@ type WorkspaceUpdatePayload {
 ### `WorkspaceUpdateErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceUpdate`."""
+"""Why `workspaceUpdate` failed."""
 enum WorkspaceUpdateErrorCode {
-  """The provided name was empty."""
+  """The name is blank."""
   NAME_REQUIRED
-  """The target workspace does not exist."""
+  """The workspace does not exist."""
   WORKSPACE_NOT_FOUND
 }
 ```
@@ -473,13 +437,15 @@ enum WorkspaceUpdateErrorCode {
 ### `WorkspaceUpdateUserError`
 
 ```graphql
-"""User-facing error for `workspaceUpdate`."""
+"""A problem that stopped `workspaceUpdate`."""
 type WorkspaceUpdateUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceUpdateErrorCode!
 }
 ```
@@ -487,16 +453,12 @@ type WorkspaceUpdateUserError {
 ### `WorkspaceDuplicateInput`
 
 ```graphql
-"""
-Input for `workspaceDuplicate`. Copies the source workspace and every
-child entity (features, conditions, actions, steps, fields, experiences,
-CMS content) into a new draft workspace on the same project.
-"""
+"""The input of `workspaceDuplicate`."""
 input WorkspaceDuplicateInput {
-  """Workspace to duplicate."""
+  """The ID of the workspace to copy."""
   sourceWorkspaceId: ID!
   """
-  Optional display name for the new workspace (defaults to `<source> (Copy)`).
+  The new workspace's name. When it is null or blank, the source's name followed by ` (Copy)`.
   """
   name: String
 }
@@ -505,13 +467,13 @@ input WorkspaceDuplicateInput {
 ### `WorkspaceDuplicatePayload`
 
 ```graphql
-"""Payload returned by `workspaceDuplicate`."""
+"""The result of `workspaceDuplicate`."""
 type WorkspaceDuplicatePayload {
-  """The newly created workspace (in `DRAFT` status)."""
+  """The new workspace, in `DRAFT`. Null when a `userError` was returned."""
   workspace: Workspace
-  """The source workspace the new one was copied from."""
+  """The workspace that was copied. Null when a `userError` was returned."""
   sourceWorkspace: Workspace
-  """Validation errors encountered while duplicating the workspace."""
+  """The problems that stopped the copy. Empty on success."""
   userErrors: [WorkspaceDuplicateUserError!]!
 }
 ```
@@ -519,9 +481,9 @@ type WorkspaceDuplicatePayload {
 ### `WorkspaceDuplicateErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceDuplicate`."""
+"""Why `workspaceDuplicate` failed."""
 enum WorkspaceDuplicateErrorCode {
-  """The source workspace does not exist."""
+  """The workspace to copy does not exist."""
   SOURCE_NOT_FOUND
 }
 ```
@@ -529,13 +491,15 @@ enum WorkspaceDuplicateErrorCode {
 ### `WorkspaceDuplicateUserError`
 
 ```graphql
-"""User-facing error for `workspaceDuplicate`."""
+"""A problem that stopped `workspaceDuplicate`."""
 type WorkspaceDuplicateUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceDuplicateErrorCode!
 }
 ```
@@ -543,11 +507,9 @@ type WorkspaceDuplicateUserError {
 ### `WorkspaceArchiveInput`
 
 ```graphql
-"""
-Input for `workspaceArchive` — move a non-live workspace to `ARCHIVED` status.
-"""
+"""The input of `workspaceArchive`."""
 input WorkspaceArchiveInput {
-  """Workspace to archive."""
+  """The ID of the workspace to archive."""
   workspaceId: ID!
 }
 ```
@@ -555,11 +517,11 @@ input WorkspaceArchiveInput {
 ### `WorkspaceArchivePayload`
 
 ```graphql
-"""Payload returned by `workspaceArchive`."""
+"""The result of `workspaceArchive`."""
 type WorkspaceArchivePayload {
-  """The archived workspace, or null if a `userError` was returned."""
+  """The archived workspace. Null when a `userError` was returned."""
   workspace: Workspace
-  """Validation errors encountered while archiving the workspace."""
+  """The problems that stopped the archive. Empty on success."""
   userErrors: [WorkspaceArchiveUserError!]!
 }
 ```
@@ -567,13 +529,11 @@ type WorkspaceArchivePayload {
 ### `WorkspaceArchiveErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceArchive`."""
+"""Why `workspaceArchive` failed."""
 enum WorkspaceArchiveErrorCode {
   """The workspace does not exist."""
   WORKSPACE_NOT_FOUND
-  """
-  Live workspaces cannot be archived — publish a different workspace first.
-  """
+  """The workspace is live."""
   WORKSPACE_IS_LIVE
 }
 ```
@@ -581,13 +541,15 @@ enum WorkspaceArchiveErrorCode {
 ### `WorkspaceArchiveUserError`
 
 ```graphql
-"""User-facing error for `workspaceArchive`."""
+"""A problem that stopped `workspaceArchive`."""
 type WorkspaceArchiveUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceArchiveErrorCode!
 }
 ```
@@ -595,11 +557,9 @@ type WorkspaceArchiveUserError {
 ### `WorkspaceUnarchiveInput`
 
 ```graphql
-"""
-Input for `workspaceUnarchive` — restore an archived workspace to `DRAFT`.
-"""
+"""The input of `workspaceUnarchive`."""
 input WorkspaceUnarchiveInput {
-  """Workspace to unarchive."""
+  """The ID of the workspace to unarchive."""
   workspaceId: ID!
 }
 ```
@@ -607,13 +567,11 @@ input WorkspaceUnarchiveInput {
 ### `WorkspaceUnarchivePayload`
 
 ```graphql
-"""Payload returned by `workspaceUnarchive`."""
+"""The result of `workspaceUnarchive`."""
 type WorkspaceUnarchivePayload {
-  """
-  The unarchived workspace (now `DRAFT`), or null if a `userError` was returned.
-  """
+  """The workspace, now `DRAFT`. Null when a `userError` was returned."""
   workspace: Workspace
-  """Validation errors encountered while unarchiving the workspace."""
+  """The problems that stopped the unarchive. Empty on success."""
   userErrors: [WorkspaceUnarchiveUserError!]!
 }
 ```
@@ -621,11 +579,11 @@ type WorkspaceUnarchivePayload {
 ### `WorkspaceUnarchiveErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceUnarchive`."""
+"""Why `workspaceUnarchive` failed."""
 enum WorkspaceUnarchiveErrorCode {
   """The workspace does not exist."""
   WORKSPACE_NOT_FOUND
-  """Only `ARCHIVED` workspaces can be unarchived."""
+  """The workspace is not `ARCHIVED`."""
   WORKSPACE_NOT_ARCHIVED
 }
 ```
@@ -633,13 +591,15 @@ enum WorkspaceUnarchiveErrorCode {
 ### `WorkspaceUnarchiveUserError`
 
 ```graphql
-"""User-facing error for `workspaceUnarchive`."""
+"""A problem that stopped `workspaceUnarchive`."""
 type WorkspaceUnarchiveUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceUnarchiveErrorCode!
 }
 ```
@@ -647,9 +607,9 @@ type WorkspaceUnarchiveUserError {
 ### `WorkspaceDeleteInput`
 
 ```graphql
-"""Input for `workspaceDelete` — soft-delete a non-live workspace."""
+"""The input of `workspaceDelete`."""
 input WorkspaceDeleteInput {
-  """Workspace to delete."""
+  """The ID of the workspace to delete."""
   workspaceId: ID!
 }
 ```
@@ -657,13 +617,11 @@ input WorkspaceDeleteInput {
 ### `WorkspaceDeletePayload`
 
 ```graphql
-"""Payload returned by `workspaceDelete`."""
+"""The result of `workspaceDelete`."""
 type WorkspaceDeletePayload {
-  """
-  The ID of the deleted workspace, or null if a `userError` was returned.
-  """
+  """The ID of the deleted workspace. Null when a `userError` was returned."""
   deletedWorkspaceId: ID
-  """Validation errors encountered while deleting the workspace."""
+  """The problems that stopped the delete. Empty on success."""
   userErrors: [WorkspaceDeleteUserError!]!
 }
 ```
@@ -671,13 +629,11 @@ type WorkspaceDeletePayload {
 ### `WorkspaceDeleteErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceDelete`."""
+"""Why `workspaceDelete` failed."""
 enum WorkspaceDeleteErrorCode {
   """The workspace does not exist."""
   WORKSPACE_NOT_FOUND
-  """
-  Live workspaces cannot be deleted — publish a different workspace first.
-  """
+  """The workspace is live."""
   WORKSPACE_IS_LIVE
 }
 ```
@@ -685,13 +641,15 @@ enum WorkspaceDeleteErrorCode {
 ### `WorkspaceDeleteUserError`
 
 ```graphql
-"""User-facing error for `workspaceDelete`."""
+"""A problem that stopped `workspaceDelete`."""
 type WorkspaceDeleteUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceDeleteErrorCode!
 }
 ```
@@ -699,13 +657,12 @@ type WorkspaceDeleteUserError {
 ### `WorkspaceExportInput`
 
 ```graphql
-"""
-Input for `workspaceExport`. To export exactly what a project serves, pass the
-id of the live `WorkspaceVersion.snapshotWorkspace`: a published version's
-snapshot workspace holds no draft changes made after it was published.
-"""
+"""The input of `workspaceExport`."""
 input WorkspaceExportInput {
-  """Workspace to export."""
+  """
+  The ID of the workspace to export. To export exactly what a project serves, pass the ID of the live
+  version's `snapshotWorkspace`.
+  """
   workspaceId: ID!
 }
 ```
@@ -713,40 +670,37 @@ input WorkspaceExportInput {
 ### `WorkspaceExportPayload`
 
 ````graphql
-"""
-Payload returned by `workspaceExport`.
-
-`bundle` is a JSON document (`formatVersion: 1`) that `workspaceImport` reads:
-
-```json
-{
-  "formatVersion": 1,
-  "source": { "apiUrl": "...", "projectId": "...", "workspaceId": "...",
-              "workspaceVersionId": "..." | null, "exportedAt": "..." },
-  "workspace": { "name": "..." },
-  "features": [], "featureVariants": [], "steps": [], "fields": [],
-  "stepFields": [], "actions": [], "actionFields": [], "conditions": [],
-  "experiences": [], "contentModels": [], "contentBlocks": [],
-  "contentEntries": [], "workflows": [],
-  "assets": [{ "id": "...", "versionId": "...", "fileName": "...",
-               "mimeType": "...", "sizeBytes": 0, "width": null, "height": null,
-               "sha256": "..." | null, "downloadUrl": "..." }]
-}
-```
-
-Entity rows use database column names and carry their source `id`, which is a
-handle inside the bundle only. Organization, project, workspace and user ids,
-timestamps and deleted rows are left out. A workflow carries its `trigger` and
-its `workflow_json` graph; its `scopes` are left out, since import derives
-them from the tools the graph names. Every asset version the Content
-Entries reference is listed once in `assets`; an asset reference without a
-version pin is pinned to the version delivery serves for it. `source` is
-provenance only.
-"""
+"""The result of `workspaceExport`."""
 type WorkspaceExportPayload {
-  """The bundle, or null if a `userError` was returned."""
+  """
+  The bundle: a JSON document (`formatVersion: 1`) that `workspaceImport` reads. Null when a
+  `userError` was returned.
+  
+  ```json
+  {
+    "formatVersion": 1,
+    "source": { "apiUrl": "...", "projectId": "...", "workspaceId": "...",
+                "workspaceVersionId": "..." | null, "exportedAt": "..." },
+    "workspace": { "name": "..." },
+    "features": [], "featureVariants": [], "steps": [], "fields": [],
+    "stepFields": [], "actions": [], "actionFields": [], "conditions": [],
+    "experiences": [], "contentModels": [], "contentBlocks": [],
+    "contentEntries": [], "workflows": [],
+    "assets": [{ "id": "...", "versionId": "...", "fileName": "...",
+                 "mimeType": "...", "sizeBytes": 0, "width": null, "height": null,
+                 "sha256": "..." | null, "downloadUrl": "..." }]
+  }
+  ```
+  
+  Entities use snake_case keys and carry their source `id`, which is a handle inside the bundle
+  only. Organisation, project, workspace and user IDs, timestamps and deleted entities are left out.
+  A workflow carries its `trigger` and its `workflow_json` graph, without its scopes. Every asset
+  version the content entries reference is listed once in `assets`; a reference that pins no version
+  is pinned to the version the Delivery API serves for it. `source` records where the bundle came
+  from.
+  """
   bundle: JSON
-  """Errors that stopped the export. Empty on success."""
+  """The problems that stopped the export. Empty on success."""
   userErrors: [WorkspaceExportUserError!]!
 }
 ````
@@ -754,25 +708,26 @@ type WorkspaceExportPayload {
 ### `WorkspaceExportErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceExport`."""
+"""Why `workspaceExport` failed."""
 enum WorkspaceExportErrorCode {
   """The workspace does not exist."""
   WORKSPACE_NOT_FOUND
   """
-  A Content Entry references an asset version that no longer exists in the project. The message names the entry and the asset.
+  A content entry references an asset version that does not exist in the project. The message
+  names the entry and the asset.
   """
   ASSET_NOT_FOUND
   """
-  A stored row does not fit the bundle format, even after experience `flow_json` is read the way the app serves it, or a Content Entry holds an asset version where its schema places no asset field, which `workspaceImport` cannot remap. The message names the entity and the offending column or place in `data`.
+  An entity does not fit the bundle format, or a content entry holds an asset version where its
+  schema has no asset field, which `workspaceImport` cannot remap. The message names the entity
+  and the place at fault.
   """
   INVALID_SOURCE_ROW
   """
-  A row references an entity the workspace does not hold, such as a Content
-  Entry that embeds a deleted Content Block, a flow node whose target
-  Experience is deleted, or a workflow whose trigger or tool argument names a
-  deleted Action, so `workspaceImport` would reject the bundle. One
-  error is returned per reference; its message names the entity, its key when
-  it has one, where in the entity the reference sits, and the id it references.
+  An entity references one the workspace does not hold, such as a content entry that embeds a
+  deleted Content Block, a flow node whose experience is deleted, or a workflow whose trigger or
+  tool argument names a deleted action. One error is returned per reference; its message names the
+  entity, its key when it has one, where the reference sits and the ID it references.
   """
   UNRESOLVED_REFERENCE
 }
@@ -781,13 +736,15 @@ enum WorkspaceExportErrorCode {
 ### `WorkspaceExportUserError`
 
 ```graphql
-"""User-facing error for `workspaceExport`."""
+"""A problem that stopped `workspaceExport`."""
 type WorkspaceExportUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceExportErrorCode!
 }
 ```
@@ -796,21 +753,17 @@ type WorkspaceExportUserError {
 
 ```graphql
 """
-Maps one asset version a bundle references to the asset version that stands in
-for it in the target project. Upload the bytes from the bundle's `downloadUrl`
-with `assetUploadInit` (passing `sha256`, so bytes already in the project are
-reused) and `assetCommit`, then map the bundle's `versionId` to the resulting
-`assetId` and `versionId`.
+The asset version that stands in for one a bundle references. Upload the file from the bundle's
+`downloadUrl` with `assetUploadInit`, passing `sha256` so a file the project holds is reused, and
+`assetCommit`, then map the bundle's `versionId` to the result.
 """
 input WorkspaceImportAssetMappingInput {
-  """
-  The asset version id as it appears in the bundle (`assets[].versionId`).
-  """
+  """The asset version's ID in the bundle (`assets[].versionId`)."""
   sourceVersionId: ID!
-  """The target project's Asset."""
+  """The ID of the asset in the target project."""
   assetId: ID!
   """
-  The committed version of `assetId` to reference in place of `sourceVersionId`.
+  The ID of the committed version of `assetId` that replaces `sourceVersionId`.
   """
   versionId: ID!
 }
@@ -819,32 +772,19 @@ input WorkspaceImportAssetMappingInput {
 ### `WorkspaceImportInput`
 
 ```graphql
-"""
-Input for `workspaceImport`. Creates a new `DRAFT` workspace in `projectId`
-holding one copy of every entity in `bundle`, as produced by
-`workspaceExport`. Every entity gets a new id, and every reference between
-entities, including asset references through `assetMap` and the Actions a
-workflow's trigger and tool arguments name, is rewritten to the new ids. A
-workflow's graph keeps its node and edge ids, and its scopes are derived from
-the tools the graph names; the caller must be able to grant each of them, as
-when saving the graph. No existing workspace, entity or live version changes;
-publish the new workspace with `workspacePublish`.
-"""
+"""The input of `workspaceImport`."""
 input WorkspaceImportInput {
   """
-  The project to create the workspace in. May belong to a different organization than the bundle's source.
+  The ID of the project to create the workspace in. It can belong to another organisation than the bundle's source.
   """
   projectId: ID!
-  """
-  Display name for the new workspace. Defaults to the bundle's `workspace.name`.
-  """
+  """The new workspace's name. Null for the bundle's `workspace.name`."""
   name: String
-  """The bundle returned by `workspaceExport` (`formatVersion: 1`)."""
+  """The bundle `workspaceExport` returned (`formatVersion: 1`)."""
   bundle: JSON!
   """
-  The target asset version for every asset version the bundle references.
-  Every mapped target must be a committed version of a non-deleted Asset in
-  `projectId`.
+  The stand-in for every asset version the bundle references. Each must be a committed version of an
+  asset in `projectId`.
   """
   assetMap: [WorkspaceImportAssetMappingInput!]
 }
@@ -853,14 +793,12 @@ input WorkspaceImportInput {
 ### `WorkspaceImportPayload`
 
 ```graphql
-"""Payload returned by `workspaceImport`."""
+"""The result of `workspaceImport`."""
 type WorkspaceImportPayload {
-  """
-  The new workspace (in `DRAFT` status), or null if a `userError` was returned.
-  """
+  """The new workspace, in `DRAFT`. Null when a `userError` was returned."""
   workspace: Workspace
   """
-  Errors that stopped the import. When any is returned, nothing was created.
+  The problems that stopped the import. When any is returned, nothing was created.
   """
   userErrors: [WorkspaceImportUserError!]!
 }
@@ -869,7 +807,7 @@ type WorkspaceImportPayload {
 ### `WorkspaceImportErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `workspaceImport`."""
+"""Why `workspaceImport` failed."""
 enum WorkspaceImportErrorCode {
   """The target project does not exist."""
   PROJECT_NOT_FOUND
@@ -880,23 +818,30 @@ enum WorkspaceImportErrorCode {
   """The bundle's `formatVersion` is not one this server reads."""
   UNSUPPORTED_FORMAT_VERSION
   """
-  The bundle does not match its format: a missing or unknown collection or column, a value of the wrong type, a content model or block schema that does not parse, a repeated id, or a workflow whose visit cap or loops the workflow save check refuses. `field` points into the bundle.
+  The bundle does not match its format: a missing or unknown collection or key, a value of the
+  wrong type, a Content Model or Content Block schema that does not parse, a repeated ID, or a
+  workflow whose visit cap or loops a workflow save refuses. `field` points into the bundle.
   """
   INVALID_BUNDLE
   """
-  An entity references an id that is not in the bundle. One error is returned per reference; its message names the entity, its key when it has one, where in the entity the reference sits, and the id it references.
+  An entity references an ID that is not in the bundle. One error is returned per reference; its
+  message names the entity, its key when it has one, where the reference sits and the ID it
+  references.
   """
   UNRESOLVED_REFERENCE
   """
-  An `assetMap` item names an asset version that is not a committed version of a non-deleted Asset in the target project, or maps one source version to two targets.
+  An `assetMap` item names an asset version that is not a committed version of an asset in the
+  target project, or maps one source version to two targets.
   """
   INVALID_ASSET_MAPPING
   """
-  A Content Entry references an asset version that `assetMap` does not map, or holds a bundle asset version where its schema places no asset field, so the reference cannot be remapped.
+  A content entry references an asset version that `assetMap` does not map, or holds one where its
+  schema has no asset field.
   """
   UNMAPPED_ASSET
   """
-  A workflow's tools need a scope the caller neither holds nor gets by default, so the caller could not save its graph. The message names the workflow, each tool and the scope it needs.
+  A workflow's tools need a scope the caller cannot grant. The message names the workflow, each
+  tool and the scope it needs.
   """
   WORKFLOW_SCOPES_NOT_HELD
 }
@@ -905,13 +850,15 @@ enum WorkspaceImportErrorCode {
 ### `WorkspaceImportUserError`
 
 ```graphql
-"""User-facing error for `workspaceImport`."""
+"""A problem that stopped `workspaceImport`."""
 type WorkspaceImportUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error's code."""
   code: WorkspaceImportErrorCode!
 }
 ```