picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,917 @@
+---
+type: reference
+layout: docs
+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.
+
+## Queries
+
+### `workspace`
+
+Get a specific workspace. Requires authentication.
+
+```graphql
+workspace(id: ID!, 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.
+
+```graphql
+workspaceExport(input: WorkspaceExportInput!): WorkspaceExportPayload! @auth
+```
+
+## Mutations
+
+### `workspacePublish`
+
+Publish a workspace, creating an immutable version snapshot. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+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`.
+
+```graphql
+workspaceVersionPublish(input: WorkspaceVersionPublishInput!): WorkspaceVersionPublishPayload! @auth
+```
+
+### `workspaceCreate`
+
+Create a new workspace on a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceCreate(input: WorkspaceCreateInput!): WorkspaceCreatePayload! @auth
+```
+
+### `workspaceUpdate`
+
+Rename an existing workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceUpdate(input: WorkspaceUpdateInput!): WorkspaceUpdatePayload! @auth
+```
+
+### `workspaceDuplicate`
+
+Duplicate an existing workspace with all of its child entities, including its workflows. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceDuplicate(input: WorkspaceDuplicateInput!): WorkspaceDuplicatePayload! @auth
+```
+
+### `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.
+
+```graphql
+workspaceImport(input: WorkspaceImportInput!): WorkspaceImportPayload! @auth
+```
+
+### `workspaceArchive`
+
+Archive a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceArchive(input: WorkspaceArchiveInput!): WorkspaceArchivePayload! @auth
+```
+
+### `workspaceUnarchive`
+
+Unarchive an archived workspace (restores it to `DRAFT`). Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceUnarchive(input: WorkspaceUnarchiveInput!): WorkspaceUnarchivePayload! @auth
+```
+
+### `workspaceDelete`
+
+Soft-delete a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+workspaceDelete(input: WorkspaceDeleteInput!): WorkspaceDeletePayload! @auth
+```
+
+## Types
+
+### `WorkspaceStatus`
+
+```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.
+"""
+enum WorkspaceStatus {
+  """Workspace is in draft mode: editable, not yet served by SDKs."""
+  DRAFT
+  """Workspace owns the project's served version (derived, not stored)."""
+  LIVE
+  """Workspace has been archived: read-only audit state."""
+  ARCHIVED
+  """
+  Per-publish snapshot copy: excluded from workspace listings, reachable via `WorkspaceVersion.snapshotWorkspace`.
+  """
+  HIDDEN
+}
+```
+
+### `Workspace`
+
+```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`.
+"""
+type Workspace {
+  """Unique workspace identifier."""
+  id: ID!
+  """User-facing display name."""
+  name: String!
+  """Current status of the workspace."""
+  status: WorkspaceStatus!
+  """The project this workspace belongs to."""
+  project: Project!
+  """The project ID this workspace belongs to."""
+  projectId: ID!
+  """Conditions within this workspace."""
+  conditions(first: Int, after: String, last: Int, before: String): ConditionConnection!
+  """Steps within this workspace."""
+  steps(first: Int, after: String, last: Int, before: String): StepConnection!
+  """Fields within this workspace."""
+  fields(first: Int, after: String, last: Int, before: String): FieldConnection!
+  """Actions within this workspace."""
+  actions(first: Int, after: String, last: Int, before: String): ActionConnection!
+  """Features within this workspace."""
+  features(first: Int, after: String, last: Int, before: String): FeatureConnection!
+  """
+  Experiences within this workspace, optionally filtered by type (`FLOW` / `PAGE`).
+  """
+  experiences(type: ExperienceType, first: Int, after: String, last: Int, before: String): ExperienceConnection!
+  """Workflows within this workspace."""
+  workflows(first: Int, after: String, last: Int, before: String): WorkflowConnection!
+  """
+  CMS Content Models within this workspace, optionally filtered by category.
+  """
+  contentModels(category: ContentModelCategory, first: Int, after: String, last: Int, before: String): ContentModelConnection!
+  """
+  CMS Content Blocks within this workspace, optionally filtered by category.
+  """
+  contentBlocks(category: ContentBlockCategory, first: Int, after: String, last: Int, before: String): ContentBlockConnection!
+  """
+  CMS Content Entries within this workspace, optionally filtered by parent Content Model.
+  """
+  contentEntries(contentModelId: ID, first: Int, after: String, last: Int, before: String): ContentEntryConnection!
+  """Preview token for previewing unpublished workspace changes in the SDK."""
+  previewToken: String!
+  """When this 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).
+  """
+  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`.
+  """
+  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)`.
+  """
+  versions(first: Int, after: String, last: Int, before: String): WorkspaceVersionConnection!
+}
+```
+
+### `WorkspaceEdge`
+
+```graphql
+"""Edge type for `WorkspaceConnection`."""
+type WorkspaceEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The workspace."""
+  node: Workspace!
+}
+```
+
+### `WorkspaceConnection`
+
+```graphql
+"""Relay-style connection of workspaces."""
+type WorkspaceConnection {
+  """List of workspace edges."""
+  edges: [WorkspaceEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of workspaces."""
+  totalCount: Int!
+}
+```
+
+### `WorkspacePublishInput`
+
+```graphql
+"""Input for `workspacePublish` — promote a draft workspace to live."""
+input WorkspacePublishInput {
+  """
+  Project ID. Derived from `workspaceId`; kept for backwards compatibility.
+  """
+  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).
+  """
+  workspaceId: ID!
+}
+```
+
+### `WorkspacePublishPayload`
+
+```graphql
+"""Payload returned by `workspacePublish`."""
+type WorkspacePublishPayload {
+  """The published workspace, now in `LIVE` status."""
+  workspace: Workspace
+  """
+  Validation errors encountered during publish. Empty array indicates success.
+  """
+  userErrors: [WorkspacePublishUserError!]!
+}
+```
+
+### `WorkspacePublishErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspacePublish`."""
+enum WorkspacePublishErrorCode {
+  """The target workspace does not exist."""
+  WORKSPACE_NOT_FOUND
+  """
+  The target workspace is already live; publishing a live workspace is not allowed.
+  """
+  WORKSPACE_ALREADY_LIVE
+}
+```
+
+### `WorkspacePublishUserError`
+
+```graphql
+"""User-facing error for `workspacePublish`."""
+type WorkspacePublishUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspacePublishErrorCode!
+}
+```
+
+### `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.
+"""
+input WorkspaceVersionPublishInput {
+  """
+  A previously-published `WorkspaceVersion` to make its project's served version.
+  """
+  workspaceVersionId: ID!
+}
+```
+
+### `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.
+"""
+type WorkspaceVersionPublishPayload {
+  """
+  The workspace now serving the published version, or null if a `userError` was returned.
+  """
+  workspace: Workspace
+  """
+  Validation errors encountered while publishing the version. Empty array indicates success.
+  """
+  userErrors: [WorkspaceVersionPublishUserError!]!
+}
+```
+
+### `WorkspaceVersionPublishErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceVersionPublish`."""
+enum WorkspaceVersionPublishErrorCode {
+  """The version's owning workspace no longer exists (e.g. it was deleted)."""
+  WORKSPACE_NOT_FOUND
+  """The target `workspaceVersionId` 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.
+  """
+  WORKSPACE_VERSION_ALREADY_LIVE
+}
+```
+
+### `WorkspaceVersionPublishUserError`
+
+```graphql
+"""User-facing error for `workspaceVersionPublish`."""
+type WorkspaceVersionPublishUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceVersionPublishErrorCode!
+}
+```
+
+### `WorkspaceCreateInput`
+
+```graphql
+"""Input for `workspaceCreate`."""
+input WorkspaceCreateInput {
+  """Project to create the workspace in."""
+  projectId: ID!
+  """User-facing display name for the new workspace."""
+  name: String!
+}
+```
+
+### `WorkspaceCreatePayload`
+
+```graphql
+"""Payload returned by `workspaceCreate`."""
+type WorkspaceCreatePayload {
+  """The newly created workspace (in `DRAFT` status)."""
+  workspace: Workspace
+  """Validation errors encountered while creating the workspace."""
+  userErrors: [WorkspaceCreateUserError!]!
+}
+```
+
+### `WorkspaceCreateErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceCreate`."""
+enum WorkspaceCreateErrorCode {
+  """The provided name was empty."""
+  NAME_REQUIRED
+  """The target project does not exist."""
+  PROJECT_NOT_FOUND
+}
+```
+
+### `WorkspaceCreateUserError`
+
+```graphql
+"""User-facing error for `workspaceCreate`."""
+type WorkspaceCreateUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceCreateErrorCode!
+}
+```
+
+### `WorkspaceUpdateInput`
+
+```graphql
+"""Input for `workspaceUpdate` — only the display name is mutable."""
+input WorkspaceUpdateInput {
+  """Workspace to rename."""
+  workspaceId: ID!
+  """New display name."""
+  name: String!
+}
+```
+
+### `WorkspaceUpdatePayload`
+
+```graphql
+"""Payload returned by `workspaceUpdate`."""
+type WorkspaceUpdatePayload {
+  """The updated workspace."""
+  workspace: Workspace
+  """Validation errors encountered while updating the workspace."""
+  userErrors: [WorkspaceUpdateUserError!]!
+}
+```
+
+### `WorkspaceUpdateErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceUpdate`."""
+enum WorkspaceUpdateErrorCode {
+  """The provided name was empty."""
+  NAME_REQUIRED
+  """The target workspace does not exist."""
+  WORKSPACE_NOT_FOUND
+}
+```
+
+### `WorkspaceUpdateUserError`
+
+```graphql
+"""User-facing error for `workspaceUpdate`."""
+type WorkspaceUpdateUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceUpdateErrorCode!
+}
+```
+
+### `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.
+"""
+input WorkspaceDuplicateInput {
+  """Workspace to duplicate."""
+  sourceWorkspaceId: ID!
+  """
+  Optional display name for the new workspace (defaults to `<source> (Copy)`).
+  """
+  name: String
+}
+```
+
+### `WorkspaceDuplicatePayload`
+
+```graphql
+"""Payload returned by `workspaceDuplicate`."""
+type WorkspaceDuplicatePayload {
+  """The newly created workspace (in `DRAFT` status)."""
+  workspace: Workspace
+  """The source workspace the new one was copied from."""
+  sourceWorkspace: Workspace
+  """Validation errors encountered while duplicating the workspace."""
+  userErrors: [WorkspaceDuplicateUserError!]!
+}
+```
+
+### `WorkspaceDuplicateErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceDuplicate`."""
+enum WorkspaceDuplicateErrorCode {
+  """The source workspace does not exist."""
+  SOURCE_NOT_FOUND
+}
+```
+
+### `WorkspaceDuplicateUserError`
+
+```graphql
+"""User-facing error for `workspaceDuplicate`."""
+type WorkspaceDuplicateUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceDuplicateErrorCode!
+}
+```
+
+### `WorkspaceArchiveInput`
+
+```graphql
+"""
+Input for `workspaceArchive` — move a non-live workspace to `ARCHIVED` status.
+"""
+input WorkspaceArchiveInput {
+  """Workspace to archive."""
+  workspaceId: ID!
+}
+```
+
+### `WorkspaceArchivePayload`
+
+```graphql
+"""Payload returned by `workspaceArchive`."""
+type WorkspaceArchivePayload {
+  """The archived workspace, or null if a `userError` was returned."""
+  workspace: Workspace
+  """Validation errors encountered while archiving the workspace."""
+  userErrors: [WorkspaceArchiveUserError!]!
+}
+```
+
+### `WorkspaceArchiveErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceArchive`."""
+enum WorkspaceArchiveErrorCode {
+  """The workspace does not exist."""
+  WORKSPACE_NOT_FOUND
+  """
+  Live workspaces cannot be archived — publish a different workspace first.
+  """
+  WORKSPACE_IS_LIVE
+}
+```
+
+### `WorkspaceArchiveUserError`
+
+```graphql
+"""User-facing error for `workspaceArchive`."""
+type WorkspaceArchiveUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceArchiveErrorCode!
+}
+```
+
+### `WorkspaceUnarchiveInput`
+
+```graphql
+"""
+Input for `workspaceUnarchive` — restore an archived workspace to `DRAFT`.
+"""
+input WorkspaceUnarchiveInput {
+  """Workspace to unarchive."""
+  workspaceId: ID!
+}
+```
+
+### `WorkspaceUnarchivePayload`
+
+```graphql
+"""Payload returned by `workspaceUnarchive`."""
+type WorkspaceUnarchivePayload {
+  """
+  The unarchived workspace (now `DRAFT`), or null if a `userError` was returned.
+  """
+  workspace: Workspace
+  """Validation errors encountered while unarchiving the workspace."""
+  userErrors: [WorkspaceUnarchiveUserError!]!
+}
+```
+
+### `WorkspaceUnarchiveErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceUnarchive`."""
+enum WorkspaceUnarchiveErrorCode {
+  """The workspace does not exist."""
+  WORKSPACE_NOT_FOUND
+  """Only `ARCHIVED` workspaces can be unarchived."""
+  WORKSPACE_NOT_ARCHIVED
+}
+```
+
+### `WorkspaceUnarchiveUserError`
+
+```graphql
+"""User-facing error for `workspaceUnarchive`."""
+type WorkspaceUnarchiveUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceUnarchiveErrorCode!
+}
+```
+
+### `WorkspaceDeleteInput`
+
+```graphql
+"""Input for `workspaceDelete` — soft-delete a non-live workspace."""
+input WorkspaceDeleteInput {
+  """Workspace to delete."""
+  workspaceId: ID!
+}
+```
+
+### `WorkspaceDeletePayload`
+
+```graphql
+"""Payload returned by `workspaceDelete`."""
+type WorkspaceDeletePayload {
+  """
+  The ID of the deleted workspace, or null if a `userError` was returned.
+  """
+  deletedWorkspaceId: ID
+  """Validation errors encountered while deleting the workspace."""
+  userErrors: [WorkspaceDeleteUserError!]!
+}
+```
+
+### `WorkspaceDeleteErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceDelete`."""
+enum WorkspaceDeleteErrorCode {
+  """The workspace does not exist."""
+  WORKSPACE_NOT_FOUND
+  """
+  Live workspaces cannot be deleted — publish a different workspace first.
+  """
+  WORKSPACE_IS_LIVE
+}
+```
+
+### `WorkspaceDeleteUserError`
+
+```graphql
+"""User-facing error for `workspaceDelete`."""
+type WorkspaceDeleteUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceDeleteErrorCode!
+}
+```
+
+### `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.
+"""
+input WorkspaceExportInput {
+  """Workspace to export."""
+  workspaceId: ID!
+}
+```
+
+### `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.
+"""
+type WorkspaceExportPayload {
+  """The bundle, or null if a `userError` was returned."""
+  bundle: JSON
+  """Errors that stopped the export. Empty on success."""
+  userErrors: [WorkspaceExportUserError!]!
+}
+````
+
+### `WorkspaceExportErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceExport`."""
+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.
+  """
+  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`.
+  """
+  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.
+  """
+  UNRESOLVED_REFERENCE
+}
+```
+
+### `WorkspaceExportUserError`
+
+```graphql
+"""User-facing error for `workspaceExport`."""
+type WorkspaceExportUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceExportErrorCode!
+}
+```
+
+### `WorkspaceImportAssetMappingInput`
+
+```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`.
+"""
+input WorkspaceImportAssetMappingInput {
+  """
+  The asset version id as it appears in the bundle (`assets[].versionId`).
+  """
+  sourceVersionId: ID!
+  """The target project's Asset."""
+  assetId: ID!
+  """
+  The committed version of `assetId` to reference in place of `sourceVersionId`.
+  """
+  versionId: ID!
+}
+```
+
+### `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`.
+"""
+input WorkspaceImportInput {
+  """
+  The project to create the workspace in. May belong to a different organization than the bundle's source.
+  """
+  projectId: ID!
+  """
+  Display name for the new workspace. Defaults to the bundle's `workspace.name`.
+  """
+  name: String
+  """The bundle returned by `workspaceExport` (`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`.
+  """
+  assetMap: [WorkspaceImportAssetMappingInput!]
+}
+```
+
+### `WorkspaceImportPayload`
+
+```graphql
+"""Payload returned by `workspaceImport`."""
+type WorkspaceImportPayload {
+  """
+  The new workspace (in `DRAFT` status), or null if a `userError` was returned.
+  """
+  workspace: Workspace
+  """
+  Errors that stopped the import. When any is returned, nothing was created.
+  """
+  userErrors: [WorkspaceImportUserError!]!
+}
+```
+
+### `WorkspaceImportErrorCode`
+
+```graphql
+"""Machine-readable error codes for `workspaceImport`."""
+enum WorkspaceImportErrorCode {
+  """The target project does not exist."""
+  PROJECT_NOT_FOUND
+  """
+  Neither `name` nor the bundle's `workspace.name` holds a non-blank name.
+  """
+  NAME_REQUIRED
+  """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.
+  """
+  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.
+  """
+  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.
+  """
+  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.
+  """
+  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.
+  """
+  WORKFLOW_SCOPES_NOT_HELD
+}
+```
+
+### `WorkspaceImportUserError`
+
+```graphql
+"""User-facing error for `workspaceImport`."""
+type WorkspaceImportUserError {
+  """Path to the offending input field, if applicable."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: WorkspaceImportErrorCode!
+}
+```