# Preview workflow import (/api-reference/workspace-sync/previewWorkflowImport)

`POST /api/v2/workflows/import/preview`

## Description
Validate destination mappings and configuration with workspace write access, without creating a workflow. The result reports readiness, unresolved fields, discovery instructions, and a fingerprint for mapped import with the same choices. Imported provenance never authorizes or queries a source workspace.

OAuth scope: `api:write`.

## Request Body

Portable workflow data and destination metadata for an import.

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace in which to import the workflow."
    },
    "workflow": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1,
          "description": "JSON string containing a workflow export object or bare workflow state."
        },
        {
          "type": "object",
          "additionalProperties": true,
          "description": "Workflow export object or bare workflow state."
        }
      ],
      "description": "Workflow export object, bare workflow state, or JSON string containing either form."
    },
    "folderPath": {
      "title": "Folder path input",
      "description": "Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
      "maxLength": 4096,
      "type": "string"
    },
    "name": {
      "description": "Override for the imported workflow name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "description": "Override for the imported workflow description.",
      "type": "string",
      "maxLength": 2000
    },
    "mappings": {
      "description": "Mapping entries addressed by resource kind and source identifier.",
      "maxItems": 5000,
      "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",
              "workflow"
            ],
            "description": "Resource or operation kind."
          },
          "sourceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4096,
            "description": "Untrusted source reference label; imports never use it to authorize or query a source workspace."
          },
          "targetId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Authorized destination identifier, or null to clear the mapping."
          }
        },
        "required": [
          "kind",
          "sourceId",
          "targetId"
        ],
        "additionalProperties": false
      }
    },
    "bindings": {
      "description": "Resolved and unresolved source occurrences with their destination selections.",
      "maxItems": 5000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "blockId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Source block identifier before graph ID regeneration."
          },
          "subBlockKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Registered source field key, including the tool index for nested Agent fields."
          },
          "valuePath": {
            "default": [],
            "maxItems": 8,
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 2000
                }
              ]
            },
            "description": "Path within the field value; strings address properties and numbers address array entries."
          },
          "positions": {
            "description": "Positions occupied by this identifier in a multi-value field.",
            "maxItems": 2000,
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2000
            }
          },
          "encoding": {
            "default": "scalar",
            "type": "string",
            "enum": [
              "scalar",
              "array",
              "csv",
              "files",
              "environment"
            ],
            "description": "Registered encoding used to discover and rewrite the reference."
          },
          "kind": {
            "type": "string",
            "enum": [
              "credential",
              "env-var",
              "knowledge-base",
              "knowledge-document",
              "table",
              "file",
              "file-folder",
              "mcp-server",
              "custom-tool",
              "custom-block",
              "skill",
              "sandbox",
              "workflow"
            ],
            "description": "Resource or operation kind."
          },
          "targetId": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              },
              {
                "type": "null"
              }
            ],
            "description": "Authorized destination identifier, or null to clear the mapping."
          }
        },
        "required": [
          "blockId",
          "subBlockKey",
          "kind",
          "targetId"
        ],
        "additionalProperties": false
      }
    },
    "dependentValues": {
      "description": "Destination-specific values addressed by the source block ID and field key, before imported IDs are regenerated.",
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "blockId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Source block identifier before graph ID regeneration."
          },
          "subBlockKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "description": "Registered source field key, including the tool index for nested Agent fields."
          },
          "value": {
            "type": "string",
            "maxLength": 16384,
            "description": "Destination value for the registered dependent field."
          }
        },
        "required": [
          "blockId",
          "subBlockKey",
          "value"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "workspaceId",
    "workflow"
  ],
  "additionalProperties": false,
  "title": "Import workflow request",
  "description": "Portable workflow data and destination metadata for an import."
}
```

## Responses

### 200 — Import readiness, unresolved bindings, and destination discovery instructions.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "previewFingerprint": {
          "type": "string",
          "minLength": 64,
          "maxLength": 64,
          "description": "Fingerprint to send when applying this import with the same choices. Preview again after changing any choice."
        },
        "ready": {
          "type": "boolean",
          "description": "Whether every required destination binding and configuration field is resolved for import."
        },
        "bindings": {
          "maxItems": 10000,
          "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",
                  "workflow"
                ],
                "description": "Resource or operation kind."
              },
              "sourceId": {
                "type": "string",
                "maxLength": 4096,
                "description": "Untrusted source reference label; imports never use it to authorize or query a source workspace."
              },
              "targetId": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 4096
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Authorized destination identifier, or null to clear the mapping."
              },
              "required": {
                "type": "boolean",
                "description": "Whether the reference or configuration is required for this operation."
              },
              "occurrence": {
                "type": "object",
                "properties": {
                  "blockId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Source block identifier before graph ID regeneration."
                  },
                  "subBlockKey": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Registered source field key, including the tool index for nested Agent fields."
                  },
                  "valuePath": {
                    "maxItems": 8,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 2000
                        }
                      ]
                    },
                    "description": "Path within the field value; strings address properties and numbers address array entries."
                  },
                  "positions": {
                    "description": "Positions occupied by this identifier in a multi-value field.",
                    "maxItems": 2000,
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 2000
                    }
                  },
                  "encoding": {
                    "type": "string",
                    "enum": [
                      "scalar",
                      "array",
                      "csv",
                      "files",
                      "environment"
                    ],
                    "description": "Registered encoding used to discover and rewrite the reference."
                  }
                },
                "required": [
                  "blockId",
                  "subBlockKey",
                  "valuePath",
                  "encoding"
                ],
                "additionalProperties": false,
                "description": "Registered source field occurrence addressed by this binding."
              }
            },
            "required": [
              "kind",
              "sourceId",
              "targetId",
              "required",
              "occurrence"
            ],
            "additionalProperties": false
          },
          "description": "Resolved and unresolved source occurrences with their destination selections."
        },
        "unresolvedBindings": {
          "maxItems": 10000,
          "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",
                  "workflow"
                ],
                "description": "Resource or operation kind."
              },
              "sourceId": {
                "type": "string",
                "maxLength": 4096,
                "description": "Untrusted source reference label; imports never use it to authorize or query a source workspace."
              },
              "targetId": {
                "anyOf": [
                  {
                    "type": "string",
                    "maxLength": 4096
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Authorized destination identifier, or null to clear the mapping."
              },
              "required": {
                "type": "boolean",
                "description": "Whether the reference or configuration is required for this operation."
              },
              "occurrence": {
                "type": "object",
                "properties": {
                  "blockId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Source block identifier before graph ID regeneration."
                  },
                  "subBlockKey": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 256,
                    "description": "Registered source field key, including the tool index for nested Agent fields."
                  },
                  "valuePath": {
                    "maxItems": 8,
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256
                        },
                        {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 2000
                        }
                      ]
                    },
                    "description": "Path within the field value; strings address properties and numbers address array entries."
                  },
                  "positions": {
                    "description": "Positions occupied by this identifier in a multi-value field.",
                    "maxItems": 2000,
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 2000
                    }
                  },
                  "encoding": {
                    "type": "string",
                    "enum": [
                      "scalar",
                      "array",
                      "csv",
                      "files",
                      "environment"
                    ],
                    "description": "Registered encoding used to discover and rewrite the reference."
                  }
                },
                "required": [
                  "blockId",
                  "subBlockKey",
                  "valuePath",
                  "encoding"
                ],
                "additionalProperties": false,
                "description": "Registered source field occurrence addressed by this binding."
              }
            },
            "required": [
              "kind",
              "sourceId",
              "targetId",
              "required",
              "occurrence"
            ],
            "additionalProperties": false
          },
          "description": "Source references that still require destination mappings or explicit copy choices."
        },
        "configuration": {
          "maxItems": 10000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "blockId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "Source block identifier before graph ID regeneration."
              },
              "subBlockKey": {
                "type": "string",
                "minLength": 1,
                "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."
              },
              "configured": {
                "type": "boolean",
                "description": "Whether this destination field currently has a nonempty value."
              },
              "multiSelect": {
                "description": "Whether the field accepts comma-separated selections.",
                "type": "boolean"
              },
              "selectorKey": {
                "description": "Registered selector key for discovering this field’s destination options.",
                "type": "string",
                "maxLength": 256
              },
              "context": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "maxLength": 256
                },
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 16384
                },
                "description": "Allowlisted selector dependencies scoped to the destination workspace."
              },
              "requiresAuthentication": {
                "type": "boolean",
                "description": "Whether a human must connect the provider before choices can be discovered."
              }
            },
            "required": [
              "blockId",
              "subBlockKey",
              "title",
              "required",
              "configured",
              "context",
              "requiresAuthentication"
            ],
            "additionalProperties": false
          },
          "description": "Dependent fields that may need destination-specific values."
        },
        "unresolvedConfiguration": {
          "maxItems": 10000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "blockId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "description": "Source block identifier before graph ID regeneration."
              },
              "subBlockKey": {
                "type": "string",
                "minLength": 1,
                "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."
              },
              "configured": {
                "type": "boolean",
                "description": "Whether this destination field currently has a nonempty value."
              },
              "multiSelect": {
                "description": "Whether the field accepts comma-separated selections.",
                "type": "boolean"
              },
              "selectorKey": {
                "description": "Registered selector key for discovering this field’s destination options.",
                "type": "string",
                "maxLength": 256
              },
              "context": {
                "type": "object",
                "propertyNames": {
                  "type": "string",
                  "maxLength": 256
                },
                "additionalProperties": {
                  "type": "string",
                  "maxLength": 16384
                },
                "description": "Allowlisted selector dependencies scoped to the destination workspace."
              },
              "requiresAuthentication": {
                "type": "boolean",
                "description": "Whether a human must connect the provider before choices can be discovered."
              }
            },
            "required": [
              "blockId",
              "subBlockKey",
              "title",
              "required",
              "configured",
              "context",
              "requiresAuthentication"
            ],
            "additionalProperties": false
          },
          "description": "Required destination configuration that remains empty."
        },
        "discovery": {
          "maxItems": 32,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "maxLength": 256,
                "description": "Resource or operation kind."
              },
              "command": {
                "type": "string",
                "maxLength": 1024,
                "description": "CLI command to enumerate destination candidates."
              },
              "humanAuthorizationMayBeRequired": {
                "type": "boolean",
                "description": "Whether discovery may require a human OAuth authorization step."
              }
            },
            "required": [
              "kind",
              "command",
              "humanAuthorizationMayBeRequired"
            ],
            "additionalProperties": false
          },
          "description": "CLI operations for discovering suitable destination resources."
        }
      },
      "required": [
        "previewFingerprint",
        "ready",
        "bindings",
        "unresolvedBindings",
        "configuration",
        "unresolvedConfiguration",
        "discovery"
      ],
      "additionalProperties": false,
      "title": "Workflow import preview",
      "description": "Import readiness, unresolved bindings, and destination discovery instructions."
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false,
  "title": "Preview workflow import response",
  "description": "Import readiness, unresolved bindings, and destination discovery instructions."
}
```

### 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."
      }
    }
  ]
}
```