# Preview organization access request (/api-reference/access-requests/previewOrganizationAccessRequest) `GET /api/v2/organizations/{organizationId}/access-requests/{requestId}/preview` Preview the current permission changes, affected group and audience, or member credit cap. Review `canApply`, `changes`, `impact`, and `fingerprint` before resolving. Permission changes affect the entire governing group, not only the requester. Requires organization Admin access. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:read`. ## Authentication ```json { "requirements": [ { "apiKey": [] }, { "oauthBearer": [ "api:read" ] } ], "schemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description." }, "oauthBearer": { "type": "oauth2", "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).", "flows": { "authorizationCode": { "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize", "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token", "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token", "scopes": { "api:read": "Read your workspaces, workflows, files, tables, and logs", "api:write": "Read, create, change, run, and delete resources in your workspaces", "offline_access": "Stay signed in without asking again" } } } } } } ``` Required OAuth scope: `api:read`. ## Request examples ### cURL ```bash curl --request GET 'https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview' \ --header 'X-API-Key: YOUR_API_KEY' ``` ### JavaScript ```javascript const response = await fetch("https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview", { "method": "GET", "headers": { "X-API-Key": "YOUR_API_KEY" } }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const result = await response.json(); ``` ### Python ```python import requests response = requests.request( "GET", "https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview", headers={ "X-API-Key": "YOUR_API_KEY" }, ) response.raise_for_status() result = response.json() ``` ### Go ```go package main import ( "io" "net/http" "os" ) func check(err error) { if err != nil { panic(err) } } func must[T any](value T, err error) T { check(err) return value } func main() { request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview", nil)) request.Header.Set("X-API-Key", "YOUR_API_KEY") response := must(http.DefaultClient.Do(request)) defer response.Body.Close() if response.StatusCode >= 400 { panic(response.Status) } must(io.Copy(os.Stdout, response.Body)) } ``` ### Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Example { public static void main(String[] args) throws Exception { var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview")); builder.header("X-API-Key", "YOUR_API_KEY"); var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build(); var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream()); try (var body = response.body()) { if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode()); body.transferTo(System.out); } } } ``` ### C# ```csharp using System; using System.IO; using System.Net.Http; using System.Text; using var client = new HttpClient(); using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/organizations/string/access-requests/string/preview"); request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY"); using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); response.EnsureSuccessStatusCode(); await response.Content.CopyToAsync(Console.OpenStandardOutput()); ``` ## Parameters ```json [ { "name": "organizationId", "in": "path", "required": true, "description": "Organization that owns the access requests.", "schema": { "type": "string", "minLength": 1, "description": "Organization that owns the access requests." } }, { "name": "requestId", "in": "path", "required": true, "description": "Access request identifier.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Access request identifier." } } ] ``` ## Responses ### 200 ```json { "description": "The proposed group or credit-cap change, affected audience, and fingerprint.", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "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))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "newLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Applied credit cap for a fulfilled request; null before approval or for permission changes." }, "request": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Access request identifier." }, "organizationId": { "type": "string", "minLength": 1, "description": "Organization that owns the request." }, "workspaceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, { "type": "null" } ], "description": "Workspace where access was requested; null for an organization-level request." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "feature", "description": "Kind of access being requested." }, "configKey": { "type": "string", "enum": [ "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport" ], "description": "Feature restriction key returned by access discovery." } }, "required": [ "kind", "configKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "integration", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "provider", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "model", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tool", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "knowledge_connector", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file_share_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "chat_deploy_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usage_limit", "description": "Kind of access being requested." }, "id": { "type": "string", "const": "member", "description": "Request an increase to the acting user’s member credit cap." } }, "required": [ "kind", "id" ], "additionalProperties": false } ], "description": "The requested feature, integration, model, tool, authentication mode, or member credit cap." }, "targetLabel": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable name of the requested access." }, "reason": { "type": "string", "maxLength": 1000, "description": "Reason supplied by the requester." }, "status": { "type": "string", "enum": [ "pending", "fulfilled", "declined", "cancelled", "closed" ], "description": "Current request status." }, "decisionReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Explanation for a declined or closed request; null when none was recorded." }, "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": "When the request was submitted." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the request was resolved; null while pending." }, "groupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the governing group when the request was submitted; null for credit-cap requests." }, "requester": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Requester user identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requester display name." }, "email": { "type": "string", "maxLength": 320, "description": "Requester email address." } }, "required": [ "id", "name", "email" ], "additionalProperties": false, "description": "User who submitted the request." } }, "required": [ "id", "organizationId", "workspaceId", "target", "targetLabel", "reason", "status", "decisionReason", "createdAt", "decidedAt", "groupName", "requester" ], "additionalProperties": false, "description": "Access request being reviewed." }, "changes": { "maxItems": 43, "type": "array", "items": { "type": "object", "properties": { "configKey": { "type": "string", "enum": [ "allowedIntegrations", "allowedModelProviders", "deniedModels", "deniedTools", "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "allowedFileShareAuthTypes", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "allowedChatDeployAuthTypes", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "allowedKnowledgeConnectors", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport", "deniedPartialAccessProjectIssues" ], "description": "Permission restriction changed by approval." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable permission name." }, "before": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Current value of the restriction." }, "after": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Value after applying the request." } }, "required": [ "configKey", "label", "before", "after" ], "additionalProperties": false }, "description": "Permission changes proposed for the whole governing group." }, "impact": { "type": "object", "properties": { "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected members." }, "workspaceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected workspaces." }, "workspaceNames": { "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Names of affected workspaces, capped at 100." }, "truncated": { "type": "boolean", "description": "Whether the workspace-name list is truncated; counts include the full impact." } }, "required": [ "memberCount", "workspaceCount", "workspaceNames", "truncated" ], "additionalProperties": false, "description": "Members and workspaces affected by approval." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Pass to Resolve Organization Access Request after reviewing the changes and impact." }, "canApply": { "type": "boolean", "description": "Whether this request can currently be approved." }, "unavailableReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Why approval is unavailable; null when canApply is true." }, "resolutionKind": { "type": "string", "const": "permission", "description": "Approval changes the governing permission group." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Governing group identifier." }, "name": { "type": "string", "description": "Governing group name." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Group affected by a permission approval; null for credit-cap changes." }, "currentLimitCredits": { "type": "null", "description": "Not applicable to permission changes." } }, "required": [ "newLimitCredits", "request", "changes", "impact", "fingerprint", "canApply", "unavailableReason", "resolutionKind", "group", "currentLimitCredits" ], "additionalProperties": false }, { "type": "object", "properties": { "newLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Applied credit cap for a fulfilled request; null before approval or for permission changes." }, "request": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Access request identifier." }, "organizationId": { "type": "string", "minLength": 1, "description": "Organization that owns the request." }, "workspaceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, { "type": "null" } ], "description": "Workspace where access was requested; null for an organization-level request." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "feature", "description": "Kind of access being requested." }, "configKey": { "type": "string", "enum": [ "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport" ], "description": "Feature restriction key returned by access discovery." } }, "required": [ "kind", "configKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "integration", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "provider", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "model", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tool", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "knowledge_connector", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file_share_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "chat_deploy_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usage_limit", "description": "Kind of access being requested." }, "id": { "type": "string", "const": "member", "description": "Request an increase to the acting user’s member credit cap." } }, "required": [ "kind", "id" ], "additionalProperties": false } ], "description": "The requested feature, integration, model, tool, authentication mode, or member credit cap." }, "targetLabel": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable name of the requested access." }, "reason": { "type": "string", "maxLength": 1000, "description": "Reason supplied by the requester." }, "status": { "type": "string", "enum": [ "pending", "fulfilled", "declined", "cancelled", "closed" ], "description": "Current request status." }, "decisionReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Explanation for a declined or closed request; null when none was recorded." }, "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": "When the request was submitted." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the request was resolved; null while pending." }, "groupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the governing group when the request was submitted; null for credit-cap requests." }, "requester": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Requester user identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requester display name." }, "email": { "type": "string", "maxLength": 320, "description": "Requester email address." } }, "required": [ "id", "name", "email" ], "additionalProperties": false, "description": "User who submitted the request." } }, "required": [ "id", "organizationId", "workspaceId", "target", "targetLabel", "reason", "status", "decisionReason", "createdAt", "decidedAt", "groupName", "requester" ], "additionalProperties": false, "description": "Access request being reviewed." }, "changes": { "maxItems": 43, "type": "array", "items": { "type": "object", "properties": { "configKey": { "type": "string", "enum": [ "allowedIntegrations", "allowedModelProviders", "deniedModels", "deniedTools", "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "allowedFileShareAuthTypes", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "allowedChatDeployAuthTypes", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "allowedKnowledgeConnectors", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport", "deniedPartialAccessProjectIssues" ], "description": "Permission restriction changed by approval." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable permission name." }, "before": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Current value of the restriction." }, "after": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Value after applying the request." } }, "required": [ "configKey", "label", "before", "after" ], "additionalProperties": false }, "description": "Permission changes proposed for the whole governing group." }, "impact": { "type": "object", "properties": { "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected members." }, "workspaceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected workspaces." }, "workspaceNames": { "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Names of affected workspaces, capped at 100." }, "truncated": { "type": "boolean", "description": "Whether the workspace-name list is truncated; counts include the full impact." } }, "required": [ "memberCount", "workspaceCount", "workspaceNames", "truncated" ], "additionalProperties": false, "description": "Members and workspaces affected by approval." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Pass to Resolve Organization Access Request after reviewing the changes and impact." }, "canApply": { "type": "boolean", "description": "Whether this request can currently be approved." }, "unavailableReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Why approval is unavailable; null when canApply is true." }, "resolutionKind": { "type": "string", "const": "usage_limit", "description": "Approval raises the requester’s member credit cap." }, "group": { "type": "null", "description": "Credit-cap requests do not change a permission group." }, "currentLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Current member credit cap. Approval requires a higher newLimitCredits." } }, "required": [ "newLimitCredits", "request", "changes", "impact", "fingerprint", "canApply", "unavailableReason", "resolutionKind", "group", "currentLimitCredits" ], "additionalProperties": false } ], "description": "Response data." } }, "required": [ "data" ], "additionalProperties": false, "title": "Preview organization access request response", "description": "The proposed group or credit-cap change, affected audience, and fingerprint.", "examples": [ { "data": { "resolutionKind": "permission", "request": { "id": "request-123", "organizationId": "org-123", "workspaceId": "workspace-123", "target": { "kind": "feature", "configKey": "hideTablesTab" }, "targetLabel": "Tables", "reason": "Maintain team data", "status": "pending", "decisionReason": null, "createdAt": "2026-06-01T09:00:00.000Z", "decidedAt": null, "groupName": "Engineering", "requester": { "id": "user-123", "name": "Alex Example", "email": "alex@example.com" } }, "group": { "id": "group-123", "name": "Engineering" }, "changes": [ { "configKey": "hideTablesTab", "label": "Tables", "before": true, "after": false } ], "impact": { "memberCount": 2, "workspaceCount": 1, "workspaceNames": [ "Engineering" ], "truncated": false }, "fingerprint": "current-preview-fingerprint", "canApply": true, "unavailableReason": null, "currentLimitCredits": null, "newLimitCredits": null } } ] }, "examples": { "example1": { "summary": "Response example 1", "value": { "data": { "resolutionKind": "permission", "request": { "id": "request-123", "organizationId": "org-123", "workspaceId": "workspace-123", "target": { "kind": "feature", "configKey": "hideTablesTab" }, "targetLabel": "Tables", "reason": "Maintain team data", "status": "pending", "decisionReason": null, "createdAt": "2026-06-01T09:00:00.000Z", "decidedAt": null, "groupName": "Engineering", "requester": { "id": "user-123", "name": "Alex Example", "email": "alex@example.com" } }, "group": { "id": "group-123", "name": "Engineering" }, "changes": [ { "configKey": "hideTablesTab", "label": "Tables", "before": true, "after": false } ], "impact": { "memberCount": 2, "workspaceCount": 1, "workspaceNames": [ "Engineering" ], "truncated": false }, "fingerprint": "current-preview-fingerprint", "canApply": true, "unavailableReason": null, "currentLimitCredits": null, "newLimitCredits": null } } } } } } } ``` ### 400 ```json { "description": "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.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } } ``` ### 401 ```json { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } } ``` ### 403 ```json { "description": "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.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } } ``` ### 404 ```json { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } } ``` ### 409 ```json { "description": "The request conflicts with current resource state.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current state of the resource" } } } } } ``` ### 429 ```json { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } } ``` ### 500 ```json { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } } ``` ### 503 ```json { "description": "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.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } } }, "content": { "application/json": { "schema": { "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." } } ] }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } ``` ## Referenced schemas The following definitions preserve recursive references and composition exactly. ```json { "#/components/headers/X-RateLimit-Limit": { "description": "Maximum requests allowed in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit", "description": "Maximum requests allowed in the current window." } }, "#/components/headers/X-RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Rate limit remaining", "description": "Requests remaining in the current window." } }, "#/components/headers/X-RateLimit-Reset": { "description": "ISO 8601 timestamp when the current rate-limit window resets.", "schema": { "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))$", "title": "Rate limit reset", "description": "ISO 8601 timestamp when the current rate-limit window resets." } }, "#/components/schemas/PreviewOrganizationAccessRequestResponse": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/V2PermissionAccessRequestPreview" }, { "$ref": "#/components/schemas/V2CreditLimitAccessRequestPreview" } ], "description": "Response data." } }, "required": [ "data" ], "additionalProperties": false, "title": "Preview organization access request response", "description": "The proposed group or credit-cap change, affected audience, and fingerprint.", "examples": [ { "data": { "resolutionKind": "permission", "request": { "id": "request-123", "organizationId": "org-123", "workspaceId": "workspace-123", "target": { "kind": "feature", "configKey": "hideTablesTab" }, "targetLabel": "Tables", "reason": "Maintain team data", "status": "pending", "decisionReason": null, "createdAt": "2026-06-01T09:00:00.000Z", "decidedAt": null, "groupName": "Engineering", "requester": { "id": "user-123", "name": "Alex Example", "email": "alex@example.com" } }, "group": { "id": "group-123", "name": "Engineering" }, "changes": [ { "configKey": "hideTablesTab", "label": "Tables", "before": true, "after": false } ], "impact": { "memberCount": 2, "workspaceCount": 1, "workspaceNames": [ "Engineering" ], "truncated": false }, "fingerprint": "current-preview-fingerprint", "canApply": true, "unavailableReason": null, "currentLimitCredits": null, "newLimitCredits": null } } ] }, "#/components/schemas/V2PermissionAccessRequestPreview": { "type": "object", "properties": { "newLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Applied credit cap for a fulfilled request; null before approval or for permission changes." }, "request": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Access request identifier." }, "organizationId": { "type": "string", "minLength": 1, "description": "Organization that owns the request." }, "workspaceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, { "type": "null" } ], "description": "Workspace where access was requested; null for an organization-level request." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "feature", "description": "Kind of access being requested." }, "configKey": { "type": "string", "enum": [ "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport" ], "description": "Feature restriction key returned by access discovery." } }, "required": [ "kind", "configKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "integration", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "provider", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "model", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tool", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "knowledge_connector", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file_share_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "chat_deploy_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usage_limit", "description": "Kind of access being requested." }, "id": { "type": "string", "const": "member", "description": "Request an increase to the acting user’s member credit cap." } }, "required": [ "kind", "id" ], "additionalProperties": false } ], "description": "The requested feature, integration, model, tool, authentication mode, or member credit cap." }, "targetLabel": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable name of the requested access." }, "reason": { "type": "string", "maxLength": 1000, "description": "Reason supplied by the requester." }, "status": { "type": "string", "enum": [ "pending", "fulfilled", "declined", "cancelled", "closed" ], "description": "Current request status." }, "decisionReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Explanation for a declined or closed request; null when none was recorded." }, "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": "When the request was submitted." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the request was resolved; null while pending." }, "groupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the governing group when the request was submitted; null for credit-cap requests." }, "requester": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Requester user identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requester display name." }, "email": { "type": "string", "maxLength": 320, "description": "Requester email address." } }, "required": [ "id", "name", "email" ], "additionalProperties": false, "description": "User who submitted the request." } }, "required": [ "id", "organizationId", "workspaceId", "target", "targetLabel", "reason", "status", "decisionReason", "createdAt", "decidedAt", "groupName", "requester" ], "additionalProperties": false, "description": "Access request being reviewed." }, "changes": { "maxItems": 43, "type": "array", "items": { "type": "object", "properties": { "configKey": { "type": "string", "enum": [ "allowedIntegrations", "allowedModelProviders", "deniedModels", "deniedTools", "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "allowedFileShareAuthTypes", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "allowedChatDeployAuthTypes", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "allowedKnowledgeConnectors", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport", "deniedPartialAccessProjectIssues" ], "description": "Permission restriction changed by approval." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable permission name." }, "before": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Current value of the restriction." }, "after": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Value after applying the request." } }, "required": [ "configKey", "label", "before", "after" ], "additionalProperties": false }, "description": "Permission changes proposed for the whole governing group." }, "impact": { "type": "object", "properties": { "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected members." }, "workspaceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected workspaces." }, "workspaceNames": { "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Names of affected workspaces, capped at 100." }, "truncated": { "type": "boolean", "description": "Whether the workspace-name list is truncated; counts include the full impact." } }, "required": [ "memberCount", "workspaceCount", "workspaceNames", "truncated" ], "additionalProperties": false, "description": "Members and workspaces affected by approval." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Pass to Resolve Organization Access Request after reviewing the changes and impact." }, "canApply": { "type": "boolean", "description": "Whether this request can currently be approved." }, "unavailableReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Why approval is unavailable; null when canApply is true." }, "resolutionKind": { "type": "string", "const": "permission", "description": "Approval changes the governing permission group." }, "group": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Governing group identifier." }, "name": { "type": "string", "description": "Governing group name." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Group affected by a permission approval; null for credit-cap changes." }, "currentLimitCredits": { "type": "null", "description": "Not applicable to permission changes." } }, "required": [ "newLimitCredits", "request", "changes", "impact", "fingerprint", "canApply", "unavailableReason", "resolutionKind", "group", "currentLimitCredits" ], "additionalProperties": false }, "#/components/schemas/V2CreditLimitAccessRequestPreview": { "type": "object", "properties": { "newLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Applied credit cap for a fulfilled request; null before approval or for permission changes." }, "request": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Access request identifier." }, "organizationId": { "type": "string", "minLength": 1, "description": "Organization that owns the request." }, "workspaceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique workspace identifier." }, { "type": "null" } ], "description": "Workspace where access was requested; null for an organization-level request." }, "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "feature", "description": "Kind of access being requested." }, "configKey": { "type": "string", "enum": [ "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport" ], "description": "Feature restriction key returned by access discovery." } }, "required": [ "kind", "configKey" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "integration", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "provider", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "model", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tool", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "knowledge_connector", "description": "Kind of access being requested." }, "id": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Identifier returned by access discovery." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "file_share_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "chat_deploy_auth", "description": "Kind of access being requested." }, "id": { "type": "string", "enum": [ "public", "password", "email", "sso" ], "description": "Authentication mode to request." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "usage_limit", "description": "Kind of access being requested." }, "id": { "type": "string", "const": "member", "description": "Request an increase to the acting user’s member credit cap." } }, "required": [ "kind", "id" ], "additionalProperties": false } ], "description": "The requested feature, integration, model, tool, authentication mode, or member credit cap." }, "targetLabel": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable name of the requested access." }, "reason": { "type": "string", "maxLength": 1000, "description": "Reason supplied by the requester." }, "status": { "type": "string", "enum": [ "pending", "fulfilled", "declined", "cancelled", "closed" ], "description": "Current request status." }, "decisionReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Explanation for a declined or closed request; null when none was recorded." }, "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": "When the request was submitted." }, "decidedAt": { "anyOf": [ { "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))$" }, { "type": "null" } ], "description": "When the request was resolved; null while pending." }, "groupName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the governing group when the request was submitted; null for credit-cap requests." }, "requester": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Requester user identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Requester display name." }, "email": { "type": "string", "maxLength": 320, "description": "Requester email address." } }, "required": [ "id", "name", "email" ], "additionalProperties": false, "description": "User who submitted the request." } }, "required": [ "id", "organizationId", "workspaceId", "target", "targetLabel", "reason", "status", "decisionReason", "createdAt", "decidedAt", "groupName", "requester" ], "additionalProperties": false, "description": "Access request being reviewed." }, "changes": { "maxItems": 43, "type": "array", "items": { "type": "object", "properties": { "configKey": { "type": "string", "enum": [ "allowedIntegrations", "allowedModelProviders", "deniedModels", "deniedTools", "hideTraceSpans", "hideKnowledgeBaseTab", "hideTablesTab", "hideCopilot", "hideIntegrationsTab", "hideSecretsTab", "hideApiKeysTab", "hideInboxTab", "hideFilesTab", "disableMcpTools", "disableCustomTools", "disableSkills", "disableInvitations", "disablePublicApi", "disablePublicFileSharing", "allowedFileShareAuthTypes", "hideDeployApi", "hideDeployMcp", "hideDeployChatbot", "allowedChatDeployAuthTypes", "disablePersonalApiKeys", "disableLogExport", "hideCostInfo", "disableKnowledgeBaseCreation", "disableKnowledgeBaseFileUpload", "allowedKnowledgeConnectors", "disableTableCreation", "disableTableExport", "disableBulkFileDownload", "disablePersonalCredentials", "disableWorkspaceCreation", "hideOrgMemberDirectory", "disableCliAccess", "disableWebhookTriggers", "disableToolAutoApproval", "hideSandboxesTab", "disableOAuthAppAccess", "disableKnowledgeBaseExport", "deniedPartialAccessProjectIssues" ], "description": "Permission restriction changed by approval." }, "label": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Human-readable permission name." }, "before": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Current value of the restriction." }, "after": { "anyOf": [ { "type": "boolean" }, { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Integrations and blocks are limited to this list. Null permits every value; an empty list permits none." } ], "description": "Value after applying the request." } }, "required": [ "configKey", "label", "before", "after" ], "additionalProperties": false }, "description": "Permission changes proposed for the whole governing group." }, "impact": { "type": "object", "properties": { "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected members." }, "workspaceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of affected workspaces." }, "workspaceNames": { "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "Names of affected workspaces, capped at 100." }, "truncated": { "type": "boolean", "description": "Whether the workspace-name list is truncated; counts include the full impact." } }, "required": [ "memberCount", "workspaceCount", "workspaceNames", "truncated" ], "additionalProperties": false, "description": "Members and workspaces affected by approval." }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Pass to Resolve Organization Access Request after reviewing the changes and impact." }, "canApply": { "type": "boolean", "description": "Whether this request can currently be approved." }, "unavailableReason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Why approval is unavailable; null when canApply is true." }, "resolutionKind": { "type": "string", "const": "usage_limit", "description": "Approval raises the requester’s member credit cap." }, "group": { "type": "null", "description": "Credit-cap requests do not change a permission group." }, "currentLimitCredits": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Current member credit cap. Approval requires a higher newLimitCredits." } }, "required": [ "newLimitCredits", "request", "changes", "impact", "fingerprint", "canApply", "unavailableReason", "resolutionKind", "group", "currentLimitCredits" ], "additionalProperties": false }, "#/components/responses/BadRequest": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request" } } } } }, "#/components/schemas/V2Error": { "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": [ { "$ref": "#/components/schemas/V2ActionableForbiddenDetails" }, { "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." } } ] }, "#/components/schemas/V2ActionableForbiddenDetails": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/V2ForbiddenDetailCode" } }, "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." }, "#/components/schemas/V2ForbiddenDetailCode": { "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." }, "#/components/responses/Unauthorized": { "description": "The API credential is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } } } } }, "#/components/responses/Forbidden": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Insufficient workspace permissions", "details": { "code": "INSUFFICIENT_WORKSPACE_ROLE" } } } } } }, "#/components/responses/NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } }, "#/components/responses/Conflict": { "description": "The request conflicts with current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "CONFLICT", "message": "The request conflicts with the current state of the resource" } } } } }, "#/components/responses/RateLimited": { "description": "The caller exceeded the request rate limit.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "API rate limit exceeded", "details": { "retryAfter": "2026-01-01T00:00:30.000Z" } } } } } }, "#/components/headers/Retry-After": { "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "title": "Retry after", "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset." } }, "#/components/responses/InternalError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } } } } }, "#/components/responses/ServiceUnavailable": { "description": "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.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2Error" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service temporarily unavailable" } } } } } } ``` [Download OpenAPI specification](/openapi.json) Source: `openapi-v2-resources.json`, operation `previewOrganizationAccessRequest`.