# Create workspace access request (/api-reference/access-requests/createWorkspaceAccessRequest)

`POST /api/v2/workspaces/{workspaceId}/access-requests`

Request access using a target from Discover workspace access requests. Requires access to an organization-owned workspace with requests enabled; external collaborators use their workspace grant. Each requester can have 100 pending requests and submit 100 in 24 hours within the organization. Matching pending requests are reused; an existing request may be closed if access is already available. Permission approvals change the governing group for all affected members. Workspace API keys return `403`; use a personal API key or scoped OAuth token.

OAuth scope: `api:write`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:write"
      ]
    }
  ],
  "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:write`.

## Request examples

### cURL

```bash
curl --request POST 'https://www.sim.ai/api/v2/workspaces/string/access-requests' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": {
    "kind": "feature",
    "configKey": "hideTablesTab"
  },
  "reason": "Maintain team data"
}'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/workspaces/string/access-requests", {
  "method": "POST",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"target\": {\n    \"kind\": \"feature\",\n    \"configKey\": \"hideTablesTab\"\n  },\n  \"reason\": \"Maintain team data\"\n}"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "POST",
    "https://www.sim.ai/api/v2/workspaces/string/access-requests",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"target\": {\n    \"kind\": \"feature\",\n    \"configKey\": \"hideTablesTab\"\n  },\n  \"reason\": \"Maintain team data\"\n}",
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

import (
  "io"
  "net/http"
  "os"
  "strings"
)

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("POST", "https://www.sim.ai/api/v2/workspaces/string/access-requests", strings.NewReader("{\n  \"target\": {\n    \"kind\": \"feature\",\n    \"configKey\": \"hideTablesTab\"\n  },\n  \"reason\": \"Maintain team data\"\n}")))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  request.Header.Set("Content-Type", "application/json")
  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/workspaces/string/access-requests"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"target\": {\n    \"kind\": \"feature\",\n    \"configKey\": \"hideTablesTab\"\n  },\n  \"reason\": \"Maintain team data\"\n}")).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("POST"), "https://www.sim.ai/api/v2/workspaces/string/access-requests");
request.Content = new StringContent("{\n  \"target\": {\n    \"kind\": \"feature\",\n    \"configKey\": \"hideTablesTab\"\n  },\n  \"reason\": \"Maintain team data\"\n}", Encoding.UTF8);
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
request.Content!.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Parameters

```json

[
  {
    "name": "workspaceId",
    "in": "path",
    "required": true,
    "description": "Workspace in which the acting user requests access.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace in which the acting user requests access."
    }
  }
]

```

## Request body

```json

{
  "required": true,
  "description": "A discovered access target and an optional reason for the request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "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": "Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable."
          },
          "reason": {
            "default": "",
            "description": "Why the acting user needs this access.",
            "type": "string",
            "maxLength": 1000
          }
        },
        "required": [
          "target"
        ],
        "additionalProperties": false,
        "title": "Create workspace access request body",
        "description": "A discovered access target and an optional reason for the request.",
        "examples": [
          {
            "target": {
              "kind": "feature",
              "configKey": "hideTablesTab"
            },
            "reason": "Maintain team data"
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Request example 1",
          "value": {
            "target": {
              "kind": "feature",
              "configKey": "hideTablesTab"
            },
            "reason": "Maintain team data"
          }
        }
      }
    }
  }
}

```

## Responses

### 200

```json

{
  "description": "The new request, matching pending request, or existing request closed because access became available.",
  "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": {
            "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": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Create workspace access request response",
        "description": "The new request, matching pending request, or existing request closed because access became available.",
        "examples": [
          {
            "data": {
              "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"
              }
            }
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": {
              "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"
              }
            }
          }
        }
      }
    }
  }
}

```

### 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"
        }
      }
    }
  }
}

```

### 413

```json

{
  "description": "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.",
  "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": "PAYLOAD_TOO_LARGE",
          "message": "Request body is too large"
        }
      }
    }
  }
}

```

### 415

```json

{
  "description": "The request uses an unsupported media type.",
  "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": "UNSUPPORTED_MEDIA_TYPE",
          "message": "Request body must be sent as application/json"
        }
      }
    }
  }
}

```

### 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/schemas/CreateWorkspaceAccessRequestBody": {
    "type": "object",
    "properties": {
      "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": "Target returned by Discover Workspace Access Requests or Discover Organization Access Requests. The target must currently be requestable."
      },
      "reason": {
        "default": "",
        "description": "Why the acting user needs this access.",
        "type": "string",
        "maxLength": 1000
      }
    },
    "required": [
      "target"
    ],
    "additionalProperties": false,
    "title": "Create workspace access request body",
    "description": "A discovered access target and an optional reason for the request.",
    "examples": [
      {
        "target": {
          "kind": "feature",
          "configKey": "hideTablesTab"
        },
        "reason": "Maintain team data"
      }
    ]
  },
  "#/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/CreateWorkspaceAccessRequestResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2AccessRequest"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Create workspace access request response",
    "description": "The new request, matching pending request, or existing request closed because access became available.",
    "examples": [
      {
        "data": {
          "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"
          }
        }
      }
    ]
  },
  "#/components/schemas/V2AccessRequest": {
    "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": "Response data."
  },
  "#/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/PayloadTooLarge": {
    "description": "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.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "PAYLOAD_TOO_LARGE",
            "message": "Request body is too large"
          }
        }
      }
    }
  },
  "#/components/responses/UnsupportedMediaType": {
    "description": "The request uses an unsupported media type.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNSUPPORTED_MEDIA_TYPE",
            "message": "Request body must be sent as application/json"
          }
        }
      }
    }
  },
  "#/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 `createWorkspaceAccessRequest`.