# Create table (/api-reference/tables/createTable)

`POST /api/v2/tables`

## Description
Create a table with a typed column schema and optional folder placement.

OAuth scope: `api:write`.

## Request Body

Workspace, table metadata, folder placement, and typed columns.

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
      "description": "Table name."
    },
    "description": {
      "description": "Optional table description.",
      "type": "string",
      "maxLength": 500
    },
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Unique workspace identifier."
    },
    "schema": {
      "type": "object",
      "properties": {
        "columns": {
          "minItems": 1,
          "maxItems": 1000,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "Optional client-provided column identifier.",
                "type": "string"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 50,
                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                "description": "Column name."
              },
              "type": {
                "type": "string",
                "enum": [
                  "string",
                  "number",
                  "currency",
                  "boolean",
                  "date",
                  "json",
                  "select"
                ],
                "description": "Column data type."
              },
              "required": {
                "description": "Whether inserts must supply a value for this column.",
                "type": "boolean"
              },
              "unique": {
                "description": "Whether values in the column must be unique.",
                "type": "boolean"
              },
              "options": {
                "description": "Select options for select-type columns.",
                "maxItems": 100,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "minLength": 1,
                      "description": "Stable select-option identifier."
                    },
                    "name": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 100,
                      "description": "Display name of the select option."
                    }
                  },
                  "required": [
                    "id",
                    "name"
                  ]
                }
              },
              "multiple": {
                "description": "Whether a select column accepts multiple values.",
                "type": "boolean"
              },
              "currencyCode": {
                "description": "ISO 4217 code for currency columns.",
                "type": "string",
                "pattern": "^[A-Za-z]{3}$"
              }
            },
            "required": [
              "name",
              "type"
            ],
            "additionalProperties": false
          },
          "description": "Initial table columns."
        }
      },
      "required": [
        "columns"
      ],
      "additionalProperties": false,
      "description": "Initial table column definitions."
    },
    "folderPath": {
      "title": "Folder path input",
      "description": "Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as \"New folder\" is `/New%20folder`: everything outside `A-Z a-z 0-9 - _ . ~` is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal `.` or `..` segment are rejected. At most 64 segments and 4096 encoded bytes.",
      "maxLength": 4096,
      "type": "string"
    }
  },
  "required": [
    "name",
    "workspaceId",
    "schema"
  ],
  "additionalProperties": false,
  "title": "Create table request",
  "description": "Workspace, table metadata, folder placement, and typed columns."
}
```

## Responses

### 201 — The created table.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique table identifier."
        },
        "webUrl": {
          "type": "string",
          "format": "uri",
          "description": "Canonical absolute URL for opening this resource in the Sim web application."
        },
        "name": {
          "type": "string",
          "description": "Table name."
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Table description, or null when none is set."
        },
        "ownerEmail": {
          "type": "string",
          "format": "email",
          "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
          "description": "Current email address of the table owner.",
          "examples": [
            "owner@example.com"
          ]
        },
        "schema": {
          "type": "object",
          "properties": {
            "columns": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "description": "Stable server-assigned column identifier.",
                    "type": "string"
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                    "description": "Column name used as the public row-data key."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "string",
                      "number",
                      "currency",
                      "boolean",
                      "date",
                      "json",
                      "select"
                    ],
                    "description": "Data type of values stored in the column."
                  },
                  "required": {
                    "default": false,
                    "description": "Whether inserts require a value for this column.",
                    "type": "boolean"
                  },
                  "unique": {
                    "default": false,
                    "description": "Whether values must be unique across table rows.",
                    "type": "boolean"
                  },
                  "workflowGroupId": {
                    "description": "Workflow group whose output populates this column.",
                    "type": "string"
                  },
                  "options": {
                    "description": "Options declared for a select column.",
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Stable select-option identifier."
                        },
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 100,
                          "description": "Display name of the select option."
                        }
                      },
                      "required": [
                        "id",
                        "name"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "multiple": {
                    "description": "Whether a select column accepts multiple options.",
                    "type": "boolean"
                  },
                  "currencyCode": {
                    "description": "ISO 4217 code for a currency column, normalized to uppercase.",
                    "type": "string",
                    "pattern": "^[A-Za-z]{3}$"
                  }
                },
                "required": [
                  "name",
                  "type",
                  "required",
                  "unique"
                ],
                "additionalProperties": false,
                "description": "A typed column in a table schema."
              },
              "description": "Table column definitions."
            }
          },
          "required": [
            "columns"
          ],
          "additionalProperties": false,
          "description": "Typed table schema."
        },
        "rowCount": {
          "type": "number",
          "description": "Current number of rows in the table."
        },
        "maxRows": {
          "type": "number",
          "description": "Maximum rows allowed by the workspace plan."
        },
        "folderPath": {
          "type": "string",
          "title": "Folder path",
          "description": "Canonical slash-prefixed folder path. `/` is the workspace root. 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
        },
        "locks": {
          "type": "object",
          "properties": {
            "schemaLocked": {
              "type": "boolean",
              "description": "Whether column-schema changes are locked."
            },
            "insertLocked": {
              "type": "boolean",
              "description": "Whether row insertion is locked."
            },
            "updateLocked": {
              "type": "boolean",
              "description": "Whether row updates are locked."
            },
            "deleteLocked": {
              "type": "boolean",
              "description": "Whether row and table deletion is locked."
            }
          },
          "required": [
            "schemaLocked",
            "insertLocked",
            "updateLocked",
            "deleteLocked"
          ],
          "additionalProperties": false,
          "description": "Read-only table governance locks."
        },
        "job": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Background job identifier, or null when unavailable."
                },
                "type": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "import",
                        "delete",
                        "export",
                        "backfill",
                        "update"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Kind of background table work."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "running",
                    "ready",
                    "failed",
                    "canceled"
                  ],
                  "description": "Current background job state."
                },
                "rowsProcessed": {
                  "type": "number",
                  "description": "Number of rows processed by the job."
                },
                "error": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Failure reason, or null when the job has not failed."
                }
              },
              "required": [
                "id",
                "type",
                "status",
                "rowsProcessed",
                "error"
              ],
              "additionalProperties": false,
              "title": "Table job state",
              "description": "Current background work associated with a table."
            },
            {
              "type": "null"
            }
          ],
          "description": "Current background job, or null when idle."
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "ISO 8601 timestamp when the table was created."
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
          "description": "ISO 8601 timestamp when the table was last modified."
        }
      },
      "required": [
        "id",
        "webUrl",
        "name",
        "description",
        "ownerEmail",
        "schema",
        "rowCount",
        "maxRows",
        "folderPath",
        "locks",
        "job",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false,
      "title": "Table",
      "description": "A user-defined table with typed columns and governance state."
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false,
  "title": "Create table response",
  "description": "The created table."
}
```

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

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

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