# Bulk delete tables and folders (/api-reference/tables/bulkDeleteTables)

`POST /api/v2/tables/bulk-delete`

## Description
Archive up to 100 selected tables and folders, including folder contents. Items succeed or fail independently, with `skipped`, `notFound`, and `failed` outcomes. `deletedItems` includes all descendants. Use Restore table or Restore folder to recover archived items.

OAuth scope: `api:write`.

## Request Body

Workspace scope, and the tables and folder paths to delete.

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace that owns every selected item."
    },
    "tableIds": {
      "default": [],
      "description": "Tables to archive, by identifier.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "folderPaths": {
      "description": "Table folders to delete, by canonical path. Each cascades to everything inside it.",
      "maxItems": 100,
      "type": "array",
      "items": {
        "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"
      }
    }
  },
  "required": [
    "workspaceId"
  ],
  "additionalProperties": false,
  "title": "Bulk delete tables request",
  "description": "Workspace scope, and the tables and folder paths to delete."
}
```

## Responses

### 200 — Per-item outcome of the bulk delete.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "deleted": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "table",
                  "folder"
                ],
                "description": "Which kind of item this entry names."
              },
              "id": {
                "type": "string",
                "description": "Table identifier, or the folder path for a folder."
              },
              "name": {
                "type": "string",
                "description": "Table name, or the folder path for a folder."
              }
            },
            "required": [
              "kind",
              "id",
              "name"
            ],
            "additionalProperties": false
          },
          "description": "Items the batch archived or deleted."
        },
        "skipped": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "table",
                  "folder"
                ],
                "description": "Which kind of item this entry names."
              },
              "id": {
                "type": "string",
                "description": "Table identifier, or the folder path for a folder."
              },
              "name": {
                "type": "string",
                "description": "Table name, or the folder path for a folder."
              }
            },
            "required": [
              "kind",
              "id",
              "name"
            ],
            "additionalProperties": false
          },
          "description": "Items dropped because a selected folder already carries them."
        },
        "notFound": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "table",
                  "folder"
                ],
                "description": "Which kind of item this entry names."
              },
              "id": {
                "type": "string",
                "description": "Table identifier, or the folder path for a folder."
              }
            },
            "required": [
              "kind",
              "id"
            ],
            "additionalProperties": false
          },
          "description": "Entries nothing active resolved to."
        },
        "failed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "table",
                  "folder"
                ],
                "description": "Which kind of item this entry names."
              },
              "id": {
                "type": "string",
                "description": "Table identifier, or the folder path for a folder."
              },
              "name": {
                "type": "string",
                "description": "Table name, or the folder path for a folder."
              },
              "reason": {
                "type": "string",
                "description": "Why this item could not be acted on."
              }
            },
            "required": [
              "kind",
              "id",
              "name",
              "reason"
            ],
            "additionalProperties": false
          },
          "description": "Items the batch could not delete."
        },
        "deletedItems": {
          "type": "object",
          "properties": {
            "tables": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Tables archived, including folder cascades."
            },
            "folders": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Folders deleted, including nested folders."
            }
          },
          "required": [
            "tables",
            "folders"
          ],
          "additionalProperties": false,
          "description": "Totals across the explicit archives and every folder cascade they triggered."
        }
      },
      "required": [
        "deleted",
        "skipped",
        "notFound",
        "failed",
        "deletedItems"
      ],
      "additionalProperties": false,
      "title": "Bulk delete tables data",
      "description": "Per-item outcome of a bulk table and folder delete."
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false,
  "title": "Bulk delete tables response",
  "description": "Per-item outcome of a bulk table and folder delete.",
  "examples": [
    {
      "data": {
        "deleted": [
          {
            "kind": "table",
            "id": "tbl_7c9e6679742540de944be07fc1f90ae7",
            "name": "Leads"
          },
          {
            "kind": "folder",
            "id": "/Sales/Archive",
            "name": "/Sales/Archive"
          }
        ],
        "skipped": [],
        "notFound": [],
        "failed": [],
        "deletedItems": {
          "tables": 1,
          "folders": 1
        }
      }
    }
  ]
}
```

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

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

### 415 — The request uses an unsupported media type.

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

### 423 — The resource is temporarily locked or unavailable; retry the request.

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