# Create organization access request (/api-reference/access-requests/createOrganizationAccessRequest)

`POST /api/v2/organizations/{organizationId}/access-requests`

Request access using a target from Discover organization access requests. Requires organization membership and requests enabled. 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/organizations/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/organizations/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/organizations/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/organizations/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/organizations/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/organizations/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": "organizationId",
    "in": "path",
    "required": true,
    "description": "Organization that owns the access requests.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Organization that owns the access requests."
    }
  }
]

```

## 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 organization 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 organization 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": null,
              "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": null,
              "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/CreateOrganizationAccessRequestBody": {
    "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 organization 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/CreateOrganizationAccessRequestResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2AccessRequest"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Create organization 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": null,
          "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 `createOrganizationAccessRequest`.