# Pull workspace (/api-reference/workspace-sync/pullWorkspace)

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

## Description
Apply a reviewed sync from the other workspace into this workspace along a direct fork edge. Requires Admin access to both workspaces. Creates unmatched deployed workflows, overwrites mapped target drafts, and archives mapped targets whose sources were deleted or archived. Undeployed sources alone do not archive targets. Billing-enabled deployments require Enterprise. Billing-disabled deployments require forking to be enabled by deployment feature configuration, such as `FORKING_ENABLED`.

Send `confirm: true`, the fingerprint from a preview with identical choices, and a stable request ID. The example hash is illustrative. Changed or unresolved plans return `409` without applying. Identical retries return the committed operation; changed inputs with that ID return `409`. Copies and deployment activation can finish after the transaction commits. Poll Get workspace operation before treating the target as ready. 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

Confirmed other-to-current choices, actual preview fingerprint, and stable request ID.

```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
      }
    },
    "requestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Stable client request ID. Reuse it with identical inputs after an uncertain response; changed inputs return 409. A new ID can apply another operation."
    },
    "previewFingerprint": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$",
      "description": "Fingerprint returned by a preview with the same choices. A changed plan returns 409; preview again. The example hash is illustrative; use the actual preview value."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Confirm replacement of mapped target drafts and archival of mapped targets whose sources were deleted or archived."
    }
  },
  "required": [
    "otherWorkspaceId",
    "requestId",
    "previewFingerprint",
    "confirm"
  ],
  "additionalProperties": false,
  "title": "Pull workspace request",
  "description": "Confirmed other-to-current choices, actual preview fingerprint, and stable request ID.",
  "examples": [
    {
      "otherWorkspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
      "requestId": "pull-support-2026-10-13",
      "previewFingerprint": "c7d158e8cbc5137a2d0a4fc37ddaeb51a3b9757485679a6ad82a7de3fdac4e3a",
      "confirm": true
    }
  ]
}
```

## Responses

### 200 — Committed pull receipt with copy and deployment readiness.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "operationId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "description": "Durable operation identifier to use for polling."
        },
        "requestId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Client request ID used to commit this operation. Reuse identical mutation inputs with this ID after an uncertain response."
        },
        "workspaceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Explicit current workspace scope."
        },
        "kind": {
          "type": "string",
          "enum": [
            "workflow_import",
            "workspace_fork",
            "workspace_push",
            "workspace_pull"
          ],
          "description": "Type of committed workspace operation."
        },
        "applied": {
          "type": "boolean",
          "const": true,
          "description": "The business transaction committed, including when follow-up work fails."
        },
        "status": {
          "type": "string",
          "enum": [
            "processing",
            "completed",
            "completed_with_warnings",
            "requires_configuration",
            "failed"
          ],
          "description": "Operation status; failed follow-up work does not undo the committed transaction."
        },
        "resourceIds": {
          "maxItems": 5000,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "description": "Identifiers of resources created or changed by the committed operation."
        },
        "issues": {
          "maxItems": 2000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "Stable machine-readable issue code."
              },
              "message": {
                "type": "string",
                "maxLength": 2048,
                "description": "Human-readable explanation of the issue."
              },
              "workflowId": {
                "description": "Workflow affected by this issue or deployment attempt.",
                "type": "string",
                "maxLength": 256
              },
              "blockId": {
                "description": "Source block identifier before graph ID regeneration.",
                "type": "string",
                "maxLength": 256
              },
              "subBlockKey": {
                "description": "Registered source field key, including the tool index for nested Agent fields.",
                "type": "string",
                "maxLength": 256
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false
          },
          "description": "Structured warnings, missing configuration, and follow-up failures."
        },
        "idMap": {
          "description": "Source graph identifiers mapped to the imported identifiers.",
          "type": "object",
          "propertyNames": {
            "type": "string",
            "maxLength": 256
          },
          "additionalProperties": {
            "type": "string",
            "maxLength": 256
          }
        },
        "deploymentOperationIds": {
          "description": "Exact deployment attempts admitted by the workspace operation.",
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 256
          }
        },
        "deployments": {
          "description": "Readiness of the exact admitted deployment attempts.",
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "operationId": {
                "type": "string",
                "maxLength": 256,
                "description": "Durable operation identifier to use for polling."
              },
              "workflowId": {
                "type": "string",
                "maxLength": 256,
                "description": "Workflow affected by this issue or deployment attempt."
              },
              "version": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991,
                "description": "Deployment version number for this admitted attempt."
              },
              "status": {
                "type": "string",
                "enum": [
                  "preparing",
                  "activating",
                  "active",
                  "failed",
                  "superseded"
                ],
                "description": "Status of this exact admitted deployment attempt."
              },
              "ready": {
                "type": "boolean",
                "description": "Whether this exact deployment attempt is active and all required components are ready."
              },
              "pendingComponents": {
                "maxItems": 32,
                "type": "array",
                "items": {
                  "type": "string",
                  "maxLength": 128
                },
                "description": "Deployment components that have not finished becoming ready."
              }
            },
            "required": [
              "operationId",
              "workflowId",
              "version",
              "status",
              "ready",
              "pendingComponents"
            ],
            "additionalProperties": false
          }
        },
        "triggerUrlChanges": {
          "description": "Public trigger paths changed by this sync, with the affected workflow names.",
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "workflowName": {
                "type": "string",
                "maxLength": 1024,
                "description": "Name of the workflow whose public trigger path stops serving."
              },
              "path": {
                "type": "string",
                "maxLength": 4096,
                "description": "Public trigger path that stops serving after this sync."
              }
            },
            "required": [
              "workflowName",
              "path"
            ],
            "additionalProperties": false
          }
        },
        "backgroundWorkId": {
          "description": "Workspace activity identifier for resource-copy progress.",
          "type": "string",
          "maxLength": 256
        },
        "copyProgress": {
          "description": "Completion status and counts for explicitly selected resource copies.",
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "completed",
                "failed"
              ],
              "description": "Background resource-copy status."
            },
            "copied": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Number of resources copied successfully."
            },
            "failed": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991,
              "description": "Number of resources that failed to copy."
            }
          },
          "required": [
            "status",
            "copied",
            "failed"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "operationId",
        "requestId",
        "workspaceId",
        "kind",
        "applied",
        "status",
        "resourceIds",
        "issues"
      ],
      "additionalProperties": false,
      "title": "Workspace operation receipt",
      "description": "Committed operation receipt, resource copies, and exact deployment readiness."
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false,
  "title": "Pull workspace response",
  "description": "Committed pull receipt with copy and deployment readiness.",
  "examples": [
    {
      "data": {
        "operationId": "e4f8d2b6-9a1c-4e3d-8b7f-5c0a2d9e6f13",
        "requestId": "pull-support-2026-10-13",
        "workspaceId": "9f4c2a10-3b7e-4d58-8f6a-2c1d0e5b7a94",
        "kind": "workspace_pull",
        "applied": true,
        "status": "processing",
        "resourceIds": [
          "destination_workflow_id"
        ],
        "issues": []
      }
    }
  ]
}
```

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