# Preview workspace pull (/api-reference/workspace-sync/previewWorkspacePull)

`POST /api/v2/workspaces/{workspaceId}/fork/pull/preview`

## Description
Preview changes from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. The plan lists workflows to create, replace, or archive; replacements overwrite target drafts with the source deployment. Proposed mappings are not saved. Dependent choices use source workflow, block, and field IDs. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`. Workspace API keys return `403`; use a personal API key or scoped OAuth token.

OAuth scope: `api:write`.

## Parameters

- **workspaceId** (path) (required) — `string`: Explicit current workspace scope.

## Request Body

Other workspace and proposed source-to-target sync choices.

```json
{
  "type": "object",
  "properties": {
    "otherWorkspaceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace on the other side of the direct fork edge."
    },
    "mappings": {
      "description": "Proposed mapping entries addressed by resource type and `sourceId`. Preview does not save them; apply commits them with the sync.",
      "maxItems": 5000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "resourceType": {
            "type": "string",
            "enum": [
              "oauth_credential",
              "service_account_credential",
              "env_var",
              "table",
              "knowledge_base",
              "file",
              "file_folder",
              "mcp_server",
              "custom_block",
              "custom_tool",
              "skill",
              "sandbox"
            ],
            "description": "Resource type stored on the canonical parent/child edge."
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "description": "Source resource identifier in the canonical source workspace."
          },
          "targetId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Authorized destination identifier, or null to clear the mapping."
          }
        },
        "required": [
          "resourceType",
          "sourceId",
          "targetId"
        ],
        "additionalProperties": false
      }
    },
    "dependentValues": {
      "description": "Destination-specific choices addressed by source workflow ID, source block ID, and field key. Omission keeps saved overrides; an explicit empty array clears them.",
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sourceWorkflowId": {
            "type": "string",
            "minLength": 1,
            "description": "Workflow identifier in the source workspace."
          },
          "sourceBlockId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Block identifier in the source workflow."
          },
          "subBlockKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "Registered source field key, including the tool index for nested Agent fields."
          },
          "value": {
            "type": "string",
            "maxLength": 65536,
            "description": "Destination value for the registered dependent field."
          }
        },
        "required": [
          "sourceWorkflowId",
          "sourceBlockId",
          "subBlockKey",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "copyResources": {
      "description": "Explicit source resources to copy before syncing the workflows.",
      "type": "object",
      "properties": {
        "knowledgeBases": {
          "description": "Source knowledge base identifiers whose documents and content are copied.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "tables": {
          "description": "Source table identifiers whose schemas and rows are copied.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "customTools": {
          "description": "Source custom tool identifiers to copy.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "skills": {
          "description": "Source skill identifiers to copy.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "files": {
          "description": "Workspace file storage keys to copy.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "mcpServers": {
          "description": "External MCP server identifiers to copy; OAuth connections require authorization in the destination.",
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "additionalProperties": false
    },
    "dropReferences": {
      "description": "Source-deleted references explicitly acknowledged for removal; live source references cannot be dropped.",
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "credential",
              "env-var",
              "knowledge-base",
              "knowledge-document",
              "table",
              "file",
              "file-folder",
              "mcp-server",
              "custom-tool",
              "custom-block",
              "skill",
              "sandbox"
            ],
            "description": "Resource or operation kind."
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "description": "Source resource identifier in the canonical source workspace."
          }
        },
        "required": [
          "kind",
          "sourceId"
        ],
        "additionalProperties": false
      }
    },
    "triggerMappings": {
      "description": "Public trigger path choices from preview.triggerSlots, addressed by source workflow and block IDs. Duplicate or unavailable choices are rejected.",
      "maxItems": 500,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sourceWorkflowId": {
            "type": "string",
            "minLength": 1,
            "description": "Workflow identifier in the source workspace."
          },
          "sourceBlockId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Source trigger block identifier from the sync preview."
          },
          "adoptPath": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "An adoptable path offered for this trigger, or null to allocate a new path."
          }
        },
        "required": [
          "sourceWorkflowId",
          "sourceBlockId",
          "adoptPath"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "otherWorkspaceId"
  ],
  "additionalProperties": false,
  "title": "Preview workspace pull request",
  "description": "Other workspace and proposed source-to-target sync choices."
}
```

## Responses

### 200 — Other-to-current workflow actions, required choices, and preview fingerprint.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "previewFingerprint": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$",
          "description": "Fingerprint to submit when applying this preview with the same choices. Preview again after changing a choice."
        },
        "sourceWorkspaceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Canonical workspace the workflows and resources are copied from."
        },
        "targetWorkspaceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Canonical workspace receiving the changes."
        },
        "ready": {
          "type": "boolean",
          "description": "Whether required bindings, configuration, and sync blockers are resolved. This does not mean the target is already deployed."
        },
        "workflows": {
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "enum": [
                  "create",
                  "replace",
                  "archive"
                ],
                "description": "Planned workflow creation, replacement, or archival."
              },
              "sourceWorkflowId": {
                "description": "Workflow identifier in the source workspace.",
                "type": "string",
                "minLength": 1
              },
              "targetWorkflowId": {
                "description": "Existing target workflow identifier; absent when apply will create a new target.",
                "type": "string",
                "minLength": 1
              },
              "name": {
                "type": "string",
                "maxLength": 1024,
                "description": "Display name of the workflow or workspace."
              },
              "comparison": {
                "description": "Last successfully synced source deployment compared with the source deployment pinned by this preview. Absent for archive actions.",
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "const": "available",
                        "description": "Both exact source snapshots are available."
                      },
                      "base": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Exact source deployment snapshot identifier."
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 2147483647,
                            "description": "Saved version number in the source workflow."
                          }
                        },
                        "required": [
                          "id",
                          "version"
                        ],
                        "additionalProperties": false,
                        "description": "Source deployment last successfully synced to this destination."
                      },
                      "target": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Exact source deployment snapshot identifier."
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 2147483647,
                            "description": "Saved version number in the source workflow."
                          }
                        },
                        "required": [
                          "id",
                          "version"
                        ],
                        "additionalProperties": false,
                        "description": "Pinned source deployment that this sync would copy."
                      }
                    },
                    "required": [
                      "status",
                      "base",
                      "target"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "status": {
                        "type": "string",
                        "const": "unavailable",
                        "description": "The source baseline cannot be compared."
                      },
                      "reason": {
                        "type": "string",
                        "enum": [
                          "new_workflow",
                          "no_baseline",
                          "missing_baseline"
                        ],
                        "description": "New destination workflow, no recorded successful sync, or deleted baseline snapshot."
                      },
                      "target": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Exact source deployment snapshot identifier."
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 2147483647,
                            "description": "Saved version number in the source workflow."
                          }
                        },
                        "required": [
                          "id",
                          "version"
                        ],
                        "additionalProperties": false,
                        "description": "Pinned source deployment that this sync would copy."
                      }
                    },
                    "required": [
                      "status",
                      "reason",
                      "target"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            },
            "required": [
              "action",
              "name"
            ],
            "additionalProperties": false
          },
          "description": "Eligible workflows and their planned actions."
        },
        "unresolvedBindings": {
          "maxItems": 10000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "maxLength": 256,
                "description": "Resource or operation kind."
              },
              "sourceId": {
                "type": "string",
                "maxLength": 4096,
                "description": "Source resource identifier in the canonical source workspace."
              },
              "blockName": {
                "description": "Display name of the affected source block.",
                "type": "string",
                "maxLength": 1024
              },
              "reason": {
                "description": "Structured explanation of the unresolved binding.",
                "type": "string",
                "maxLength": 256
              }
            },
            "required": [
              "kind",
              "sourceId"
            ],
            "additionalProperties": false
          },
          "description": "Source references that still require destination mappings or explicit copy choices."
        },
        "configuration": {
          "maxItems": 10000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "sourceWorkflowId": {
                "type": "string",
                "minLength": 1,
                "description": "Workflow identifier in the source workspace."
              },
              "sourceBlockId": {
                "type": "string",
                "maxLength": 256,
                "description": "Block identifier in the source workflow."
              },
              "subBlockKey": {
                "type": "string",
                "maxLength": 1024,
                "description": "Registered source field key, including the tool index for nested Agent fields."
              },
              "title": {
                "type": "string",
                "maxLength": 1024,
                "description": "Human-readable configuration field label."
              },
              "required": {
                "type": "boolean",
                "description": "Whether the reference or configuration is required for this operation."
              },
              "currentValue": {
                "type": "string",
                "maxLength": 65536,
                "description": "Persisted sync override or proposed override; empty when neither is configured."
              },
              "multiSelect": {
                "description": "Whether the field accepts comma-separated selections.",
                "type": "boolean"
              },
              "selectorKey": {
                "description": "Registered selector key for discovering this field’s options.",
                "type": "string",
                "maxLength": 256
              },
              "discoveryWorkspaceId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "Workspace scope for selector discovery: source for a parent being copied, otherwise destination."
              },
              "context": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "maxLength": 256
                },
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 4096
                },
                "description": "Allowlisted selector dependencies scoped to discoveryWorkspaceId."
              },
              "parentKind": {
                "type": "string",
                "enum": [
                  "credential",
                  "env-var",
                  "knowledge-base",
                  "knowledge-document",
                  "table",
                  "file",
                  "file-folder",
                  "mcp-server",
                  "custom-tool",
                  "custom-block",
                  "skill",
                  "sandbox"
                ],
                "description": "Resource kind that owns this dependent configuration."
              },
              "parentSourceId": {
                "type": "string",
                "maxLength": 4096,
                "description": "Source identifier of the parent resource being mapped."
              },
              "parentContextKey": {
                "description": "Selector context key supplied by the mapped parent resource.",
                "type": "string",
                "maxLength": 256
              }
            },
            "required": [
              "sourceWorkflowId",
              "sourceBlockId",
              "subBlockKey",
              "title",
              "required",
              "currentValue",
              "discoveryWorkspaceId",
              "context",
              "parentKind",
              "parentSourceId"
            ],
            "additionalProperties": false
          },
          "description": "Dependent fields that may need destination-specific values."
        },
        "excludedTargets": {
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1,
                "description": "Resource identifier."
              },
              "name": {
                "type": "string",
                "maxLength": 1024,
                "description": "Display name of the workflow or workspace."
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false
          },
          "description": "Target workflows explicitly excluded from sync."
        },
        "triggerSlots": {
          "maxItems": 10000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "sourceWorkflowId": {
                "type": "string",
                "minLength": 1,
                "description": "Workflow identifier in the source workspace."
              },
              "sourceBlockId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "Stable source trigger block identifier to use in trigger mappings."
              },
              "blockName": {
                "type": "string",
                "maxLength": 1024,
                "description": "Display name of the source trigger block."
              },
              "workflowName": {
                "type": "string",
                "maxLength": 1024,
                "description": "Display name of the source workflow."
              },
              "ownPath": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 4096
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Existing target trigger path, preserved automatically and not configurable."
              },
              "adoptablePaths": {
                "maxItems": 1000,
                "type": "array",
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4096
                },
                "description": "Retiring paths in the same target workflow with a compatible trigger provider."
              },
              "defaultAdoptPath": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 4096
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Default adoption when ownPath is null; null then allocates a new path."
              }
            },
            "required": [
              "sourceWorkflowId",
              "sourceBlockId",
              "blockName",
              "workflowName",
              "ownPath",
              "adoptablePaths",
              "defaultAdoptPath"
            ],
            "additionalProperties": false
          },
          "description": "Source triggers and the target paths available for explicit adoption choices."
        },
        "triggerUrlChanges": {
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "workflowName": {
                "type": "string",
                "maxLength": 1024,
                "description": "Name of the affected workflow."
              },
              "path": {
                "type": "string",
                "maxLength": 4096,
                "description": "Public trigger path that stops serving after this sync."
              }
            },
            "required": [
              "workflowName",
              "path"
            ],
            "additionalProperties": false
          },
          "description": "Retiring target trigger URLs no arriving trigger adopts."
        }
      },
      "required": [
        "previewFingerprint",
        "sourceWorkspaceId",
        "targetWorkspaceId",
        "ready",
        "workflows",
        "unresolvedBindings",
        "configuration",
        "excludedTargets",
        "triggerSlots",
        "triggerUrlChanges"
      ],
      "additionalProperties": false,
      "title": "Workspace sync preview",
      "description": "Read-only sync actions, bindings, configuration, and trigger-path choices."
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false,
  "title": "Preview workspace pull response",
  "description": "Other-to-current workflow actions, required choices, and preview fingerprint."
}
```

### 400 — The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 401 — The API credential is missing or invalid.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 403 — The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 404 — The requested resource was not found.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 409 — The request conflicts with current resource state.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 413 — The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 429 — The caller exceeded the request rate limit.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 500 — An unexpected server error occurred.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```

### 503 — A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the error."
        },
        "details": {
          "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "INSUFFICIENT_WORKSPACE_ROLE",
                    "PERSONAL_API_KEYS_DISABLED",
                    "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                    "PRINCIPAL_KIND_NOT_PERMITTED",
                    "ORGANIZATION_MEMBERSHIP_REQUIRED",
                    "ORGANIZATION_ADMIN_REQUIRED",
                    "ENTERPRISE_PLAN_REQUIRED",
                    "SSO_DISABLED",
                    "SSO_DOMAIN_NOT_VERIFIED",
                    "SSO_PROVIDER_LIMIT_REACHED",
                    "ORGANIZATION_PLAN_REQUIRED",
                    "AUDIT_LOGS_DISABLED",
                    "ACCESS_REQUESTS_DISABLED",
                    "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                    "SKILL_EDITOR_ACCESS_REQUIRED",
                    "SECRET_ADMIN_ACCESS_REQUIRED",
                    "WORKSPACE_RESOURCE_LIMIT_REACHED",
                    "PUBLIC_SHARING_NOT_ALLOWED",
                    "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                    "MCP_SERVER_URL_NOT_ALLOWED",
                    "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                    "CHAT_AUTH_MODE_NOT_PERMITTED",
                    "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                    "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                    "INTEGRATION_NOT_ALLOWED",
                    "INSUFFICIENT_SCOPE",
                    "SCIM_MANAGED_MEMBERSHIP"
                  ],
                  "title": "Forbidden detail code",
                  "description": "Stable cause code for an actionable `403` response."
                }
              },
              "required": [
                "code"
              ],
              "additionalProperties": {
                "description": "Additional context for this refusal."
              },
              "title": "Actionable forbidden details",
              "description": "Machine-readable cause and optional context for an actionable `403` response."
            },
            {
              "description": "Other structured context defined by the specific error."
            }
          ]
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": false,
      "description": "Canonical error details."
    }
  },
  "required": [
    "error"
  ],
  "additionalProperties": false,
  "title": "v2 error response",
  "description": "Canonical error envelope returned by the public v2 API.",
  "examples": [
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "The request is invalid."
      }
    }
  ]
}
```