# List connector types (/api-reference/catalog/listConnectorTypes)

`GET /api/v2/connector-types`

List connector types from the deployment’s knowledge-base connector registry. Requires workspace read access and Knowledge Base access; workspace integration allowlists and revealed preview blocks do not filter this catalog. Results default to 25 summaries per page. `detail=full` adds configuration fields. Fields with `multi: true` accept `string[]`. For picker/manual-entry pairs, send one value under `canonicalParamId`, not the field’s `id`.

OAuth scope: `api:read`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:read"
      ]
    }
  ],
  "schemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
    },
    "oauthBearer": {
      "type": "oauth2",
      "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
          "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
          "scopes": {
            "api:read": "Read your workspaces, workflows, files, tables, and logs",
            "api:write": "Read, create, change, run, and delete resources in your workspaces",
            "offline_access": "Stay signed in without asking again"
          }
        }
      }
    }
  }
}

```

Required OAuth scope: `api:read`.

## Request examples

### cURL

```bash
curl --request GET 'https://www.sim.ai/api/v2/connector-types?workspaceId=string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/connector-types?workspaceId=string", {
  "method": "GET",
  "headers": {
    "X-API-Key": "YOUR_API_KEY"
  }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "GET",
    "https://www.sim.ai/api/v2/connector-types?workspaceId=string",
    headers={
  "X-API-Key": "YOUR_API_KEY"
},
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

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

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("GET", "https://www.sim.ai/api/v2/connector-types?workspaceId=string", nil))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}
```

### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/connector-types?workspaceId=string"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    var request = builder.method("GET", HttpRequest.BodyPublishers.noBody()).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}
```

### C#

```csharp
using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://www.sim.ai/api/v2/connector-types?workspaceId=string");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Parameters

```json

[
  {
    "name": "workspaceId",
    "in": "query",
    "required": true,
    "description": "Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Workspace used to authorize Knowledge Base access to the deployment’s connector-type registry. Workspace integration allowlists and revealed preview blocks do not filter this catalog."
    }
  },
  {
    "name": "search",
    "in": "query",
    "required": false,
    "description": "Case-insensitive substring match against the connector name.",
    "schema": {
      "description": "Case-insensitive substring match against the connector name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    }
  },
  {
    "name": "detail",
    "in": "query",
    "required": false,
    "description": "Projection of each item. `summary` (the default) carries the identifier, name, description, and auth mode; `full` adds the version, the complete auth settings, the `sourceConfig` field schema, incremental-sync support, and tag definitions.",
    "schema": {
      "default": "summary",
      "description": "Projection of each item. `summary` (the default) carries the identifier, name, description, and auth mode; `full` adds the version, the complete auth settings, the `sourceConfig` field schema, incremental-sync support, and tag definitions.",
      "type": "string",
      "enum": [
        "summary",
        "full"
      ]
    }
  },
  {
    "name": "limit",
    "in": "query",
    "required": false,
    "description": "Maximum connector types to return per page. Must be a whole number from 1 to 100. Defaults to 25.",
    "schema": {
      "default": 25,
      "description": "Maximum connector types to return per page. Must be a whole number from 1 to 100. Defaults to 25.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  {
    "name": "cursor",
    "in": "query",
    "required": false,
    "description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
    "schema": {
      "description": "Opaque cursor from the previous page. Send it back with the same sort and filters; only `limit` may change. Change anything else and pagination must restart without a cursor.",
      "type": "string",
      "minLength": 1
    }
  }
]

```

## Responses

### 200

```json

{
  "description": "One page of the connector-type catalog.",
  "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": "array",
            "items": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "connectorType": {
                      "type": "string",
                      "description": "Exact identifier to send when creating a connector of this type."
                    },
                    "name": {
                      "type": "string",
                      "description": "Display name."
                    },
                    "description": {
                      "type": "string",
                      "description": "What the connector syncs."
                    },
                    "version": {
                      "type": "string",
                      "description": "Connector version."
                    },
                    "auth": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "const": "oauth",
                              "description": "Authenticates with an OAuth credential; pass `credentialId` when creating the connector."
                            },
                            "provider": {
                              "type": "string",
                              "description": "OAuth service the credential must authenticate."
                            },
                            "requiredScopes": {
                              "description": "Scopes the credential must carry.",
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "mode",
                            "provider"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "mode": {
                              "type": "string",
                              "const": "apiKey",
                              "description": "Authenticates with a stored API key; pass `apiKey`, and no `credentialId`, when creating the connector."
                            },
                            "label": {
                              "description": "Label shown above the key field.",
                              "type": "string"
                            },
                            "placeholder": {
                              "description": "Placeholder shown in the key field.",
                              "type": "string"
                            },
                            "optional": {
                              "type": "boolean",
                              "description": "Whether the key may be left blank, for a source reachable without authentication."
                            }
                          },
                          "required": [
                            "mode",
                            "optional"
                          ],
                          "additionalProperties": false
                        }
                      ],
                      "description": "How the connector authenticates against its source: `oauth` connectors take `credentialId` (GitHub also accepts a personal access token as `apiKey`), `apiKey` connectors take `apiKey`."
                    },
                    "configFields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Field identifier."
                          },
                          "title": {
                            "type": "string",
                            "description": "Human-readable label."
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "short-input",
                              "dropdown",
                              "selector"
                            ],
                            "description": "Control the field renders as. A `selector` fetches its options from the connected account."
                          },
                          "placeholder": {
                            "description": "Placeholder shown in the editor.",
                            "type": "string"
                          },
                          "required": {
                            "description": "Whether a value must be supplied.",
                            "type": "boolean"
                          },
                          "description": {
                            "description": "Authored explanation of the field.",
                            "type": "string"
                          },
                          "options": {
                            "description": "Static options, for a `dropdown` field.",
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "Value stored when this option is selected."
                                },
                                "label": {
                                  "type": "string",
                                  "description": "Human-readable option label."
                                }
                              },
                              "required": [
                                "id",
                                "label"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "selectorKey": {
                            "description": "Names the picker a `selector` field renders. Its options are fetched per workspace.",
                            "type": "string"
                          },
                          "mimeType": {
                            "description": "MIME type filter applied to the picker.",
                            "type": "string"
                          },
                          "dependsOn": {
                            "description": "Sibling fields this field is cleared by when they change.",
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "all": {
                                    "description": "Every listed field must hold a value.",
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  },
                                  "any": {
                                    "description": "At least one listed field must hold a value.",
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    }
                                  }
                                },
                                "additionalProperties": false
                              }
                            ]
                          },
                          "mode": {
                            "description": "Which half of a canonical pair this field is: `basic` is the picker, `advanced` the manual entry.",
                            "type": "string",
                            "enum": [
                              "basic",
                              "advanced"
                            ]
                          },
                          "canonicalParamId": {
                            "description": "Shared `sourceConfig` key for a picker/manual-entry pair. Send exactly one of the pair, keyed by this value rather than by the field’s own `id`.",
                            "type": "string"
                          },
                          "multi": {
                            "description": "When true the stored `sourceConfig` value is a `string[]`, not a `string`: a `selector` renders a multi-select picker and a `short-input` accepts a comma-separated list.",
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "title",
                          "type"
                        ],
                        "additionalProperties": false,
                        "title": "Connector config field",
                        "description": "One field of a knowledge-base connector’s source configuration."
                      },
                      "description": "Fields that make up the connector’s `sourceConfig`."
                    },
                    "supportsIncrementalSync": {
                      "type": "boolean",
                      "description": "Whether syncs after the first fetch only what changed."
                    },
                    "tagDefinitions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Semantic tag identifier the connector populates."
                          },
                          "displayName": {
                            "type": "string",
                            "description": "Human-readable tag name."
                          },
                          "fieldType": {
                            "type": "string",
                            "enum": [
                              "text",
                              "number",
                              "date",
                              "boolean"
                            ],
                            "description": "Value type, which decides the tag slot pool it draws from."
                          }
                        },
                        "required": [
                          "id",
                          "displayName",
                          "fieldType"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Tags this connector writes onto the documents it syncs."
                    }
                  },
                  "required": [
                    "connectorType",
                    "name",
                    "description",
                    "version",
                    "auth",
                    "configFields",
                    "supportsIncrementalSync",
                    "tagDefinitions"
                  ],
                  "additionalProperties": false,
                  "title": "Connector type",
                  "description": "A knowledge-base connector type and the configuration it accepts."
                },
                {
                  "type": "object",
                  "properties": {
                    "connectorType": {
                      "type": "string",
                      "description": "Exact identifier to send when creating a connector of this type."
                    },
                    "name": {
                      "type": "string",
                      "description": "Display name."
                    },
                    "description": {
                      "type": "string",
                      "description": "What the connector syncs."
                    },
                    "auth": {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "oauth",
                            "apiKey"
                          ],
                          "description": "How the connector authenticates against its source: `oauth` connectors take `credentialId` (GitHub also accepts a personal access token as `apiKey`), `apiKey` connectors take `apiKey`."
                        }
                      },
                      "required": [
                        "mode"
                      ],
                      "additionalProperties": false,
                      "description": "Authentication mode only. `detail=full` adds the OAuth provider and scopes, or the API-key field labels."
                    }
                  },
                  "required": [
                    "connectorType",
                    "name",
                    "description",
                    "auth"
                  ],
                  "additionalProperties": false,
                  "title": "Connector type summary",
                  "description": "A knowledge-base connector type without its configuration schema. Request `detail=full` for the config fields and tag definitions."
                }
              ]
            },
            "description": "Items in the current page."
          },
          "nextCursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
          }
        },
        "required": [
          "data",
          "nextCursor"
        ],
        "additionalProperties": false,
        "title": "List connector types response",
        "description": "Knowledge-base connector types, as summaries or with their configuration fields.",
        "examples": [
          {
            "data": [
              {
                "connectorType": "google_drive",
                "name": "Google Drive",
                "description": "Sync documents from Google Drive",
                "auth": {
                  "mode": "oauth"
                }
              }
            ],
            "nextCursor": null
          },
          {
            "data": [
              {
                "connectorType": "google_drive",
                "name": "Google Drive",
                "description": "Sync documents from Google Drive",
                "version": "1.0.0",
                "auth": {
                  "mode": "oauth",
                  "provider": "google-drive",
                  "requiredScopes": [
                    "https://www.googleapis.com/auth/drive"
                  ]
                },
                "configFields": [
                  {
                    "id": "adminEmail",
                    "title": "Crawl as",
                    "type": "short-input",
                    "placeholder": "admin@yourcompany.com",
                    "required": false,
                    "description": "The Google Workspace user this service account acts as when fetching content for connected members."
                  },
                  {
                    "id": "userEmails",
                    "title": "Users",
                    "type": "short-input",
                    "placeholder": "All active Google Workspace users",
                    "required": false,
                    "description": "Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.",
                    "multi": true
                  },
                  {
                    "id": "openSharing",
                    "title": "Openly shared files",
                    "type": "dropdown",
                    "placeholder": "Keep out of search",
                    "required": false,
                    "description": "Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.",
                    "options": [
                      {
                        "label": "Keep out of search",
                        "id": "none"
                      },
                      {
                        "label": "Anyone in the domain can find",
                        "id": "domain"
                      },
                      {
                        "label": "Anyone can find",
                        "id": "anyone"
                      }
                    ]
                  },
                  {
                    "id": "folderSelector",
                    "title": "Folders",
                    "type": "selector",
                    "placeholder": "Select one or more folders (optional)",
                    "required": false,
                    "description": "Includes files in each selected folder and its accessible subfolders.",
                    "selectorKey": "google.drive",
                    "mimeType": "application/vnd.google-apps.folder",
                    "mode": "basic",
                    "canonicalParamId": "folderId",
                    "multi": true
                  },
                  {
                    "id": "folderId",
                    "title": "Folder IDs",
                    "type": "short-input",
                    "placeholder": "e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)",
                    "required": false,
                    "description": "Includes files in each selected folder and its accessible subfolders.",
                    "mode": "advanced",
                    "canonicalParamId": "folderId",
                    "multi": true
                  },
                  {
                    "id": "fileType",
                    "title": "File Type",
                    "type": "dropdown",
                    "required": false,
                    "options": [
                      {
                        "label": "All supported files",
                        "id": "all"
                      },
                      {
                        "label": "Google Docs only",
                        "id": "documents"
                      },
                      {
                        "label": "Google Sheets only",
                        "id": "spreadsheets"
                      },
                      {
                        "label": "Google Slides only",
                        "id": "presentations"
                      },
                      {
                        "label": "Plain text files only",
                        "id": "text"
                      }
                    ]
                  },
                  {
                    "id": "maxFiles",
                    "title": "Max Files",
                    "type": "short-input",
                    "placeholder": "e.g. 500 (default: unlimited)",
                    "required": false
                  }
                ],
                "supportsIncrementalSync": false,
                "tagDefinitions": [
                  {
                    "id": "owners",
                    "displayName": "Owner",
                    "fieldType": "text"
                  },
                  {
                    "id": "fileType",
                    "displayName": "File Type",
                    "fieldType": "text"
                  },
                  {
                    "id": "lastModified",
                    "displayName": "Last Modified",
                    "fieldType": "date"
                  },
                  {
                    "id": "starred",
                    "displayName": "Starred",
                    "fieldType": "boolean"
                  }
                ]
              }
            ],
            "nextCursor": null
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": [
              {
                "connectorType": "google_drive",
                "name": "Google Drive",
                "description": "Sync documents from Google Drive",
                "auth": {
                  "mode": "oauth"
                }
              }
            ],
            "nextCursor": null
          }
        },
        "example2": {
          "summary": "Response example 2",
          "value": {
            "data": [
              {
                "connectorType": "google_drive",
                "name": "Google Drive",
                "description": "Sync documents from Google Drive",
                "version": "1.0.0",
                "auth": {
                  "mode": "oauth",
                  "provider": "google-drive",
                  "requiredScopes": [
                    "https://www.googleapis.com/auth/drive"
                  ]
                },
                "configFields": [
                  {
                    "id": "adminEmail",
                    "title": "Crawl as",
                    "type": "short-input",
                    "placeholder": "admin@yourcompany.com",
                    "required": false,
                    "description": "The Google Workspace user this service account acts as when fetching content for connected members."
                  },
                  {
                    "id": "userEmails",
                    "title": "Users",
                    "type": "short-input",
                    "placeholder": "All active Google Workspace users",
                    "required": false,
                    "description": "Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.",
                    "multi": true
                  },
                  {
                    "id": "openSharing",
                    "title": "Openly shared files",
                    "type": "dropdown",
                    "placeholder": "Keep out of search",
                    "required": false,
                    "description": "Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.",
                    "options": [
                      {
                        "label": "Keep out of search",
                        "id": "none"
                      },
                      {
                        "label": "Anyone in the domain can find",
                        "id": "domain"
                      },
                      {
                        "label": "Anyone can find",
                        "id": "anyone"
                      }
                    ]
                  },
                  {
                    "id": "folderSelector",
                    "title": "Folders",
                    "type": "selector",
                    "placeholder": "Select one or more folders (optional)",
                    "required": false,
                    "description": "Includes files in each selected folder and its accessible subfolders.",
                    "selectorKey": "google.drive",
                    "mimeType": "application/vnd.google-apps.folder",
                    "mode": "basic",
                    "canonicalParamId": "folderId",
                    "multi": true
                  },
                  {
                    "id": "folderId",
                    "title": "Folder IDs",
                    "type": "short-input",
                    "placeholder": "e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)",
                    "required": false,
                    "description": "Includes files in each selected folder and its accessible subfolders.",
                    "mode": "advanced",
                    "canonicalParamId": "folderId",
                    "multi": true
                  },
                  {
                    "id": "fileType",
                    "title": "File Type",
                    "type": "dropdown",
                    "required": false,
                    "options": [
                      {
                        "label": "All supported files",
                        "id": "all"
                      },
                      {
                        "label": "Google Docs only",
                        "id": "documents"
                      },
                      {
                        "label": "Google Sheets only",
                        "id": "spreadsheets"
                      },
                      {
                        "label": "Google Slides only",
                        "id": "presentations"
                      },
                      {
                        "label": "Plain text files only",
                        "id": "text"
                      }
                    ]
                  },
                  {
                    "id": "maxFiles",
                    "title": "Max Files",
                    "type": "short-input",
                    "placeholder": "e.g. 500 (default: unlimited)",
                    "required": false
                  }
                ],
                "supportsIncrementalSync": false,
                "tagDefinitions": [
                  {
                    "id": "owners",
                    "displayName": "Owner",
                    "fieldType": "text"
                  },
                  {
                    "id": "fileType",
                    "displayName": "File Type",
                    "fieldType": "text"
                  },
                  {
                    "id": "lastModified",
                    "displayName": "Last Modified",
                    "fieldType": "date"
                  },
                  {
                    "id": "starred",
                    "displayName": "Starred",
                    "fieldType": "boolean"
                  }
                ]
              }
            ],
            "nextCursor": null
          }
        }
      }
    }
  }
}

```

### 400

```json

{
  "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "BAD_REQUEST",
          "message": "Invalid request"
        }
      }
    }
  }
}

```

### 401

```json

{
  "description": "The API credential is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNAUTHORIZED",
          "message": "Authentication required"
        }
      }
    }
  }
}

```

### 403

```json

{
  "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "FORBIDDEN",
          "message": "Insufficient workspace permissions",
          "details": {
            "code": "INSUFFICIENT_WORKSPACE_ROLE"
          }
        }
      }
    }
  }
}

```

### 404

```json

{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found"
        }
      }
    }
  }
}

```

### 429

```json

{
  "description": "The caller exceeded the request rate limit.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "RATE_LIMITED",
          "message": "API rate limit exceeded",
          "details": {
            "retryAfter": "2026-01-01T00:00:30.000Z"
          }
        }
      }
    }
  }
}

```

### 500

```json

{
  "description": "An unexpected server error occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "Internal server error"
        }
      }
    }
  }
}

```

### 503

```json

{
  "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Service temporarily unavailable"
        }
      }
    }
  }
}

```

## Referenced schemas

The following definitions preserve recursive references and composition exactly.

```json

{
  "#/components/headers/X-RateLimit-Limit": {
    "description": "Maximum requests allowed in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit",
      "description": "Maximum requests allowed in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Remaining": {
    "description": "Requests remaining in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit remaining",
      "description": "Requests remaining in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Reset": {
    "description": "ISO 8601 timestamp when the current rate-limit window resets.",
    "schema": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "title": "Rate limit reset",
      "description": "ISO 8601 timestamp when the current rate-limit window resets."
    }
  },
  "#/components/schemas/ListConnectorTypesResponse": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/V2ConnectorType"
            },
            {
              "$ref": "#/components/schemas/V2ConnectorTypeSummary"
            }
          ]
        },
        "description": "Items in the current page."
      },
      "nextCursor": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Opaque cursor for the next page. Send it back as `cursor`; `null` means there are no more pages. Do not construct a cursor yourself."
      }
    },
    "required": [
      "data",
      "nextCursor"
    ],
    "additionalProperties": false,
    "title": "List connector types response",
    "description": "Knowledge-base connector types, as summaries or with their configuration fields.",
    "examples": [
      {
        "data": [
          {
            "connectorType": "google_drive",
            "name": "Google Drive",
            "description": "Sync documents from Google Drive",
            "auth": {
              "mode": "oauth"
            }
          }
        ],
        "nextCursor": null
      },
      {
        "data": [
          {
            "connectorType": "google_drive",
            "name": "Google Drive",
            "description": "Sync documents from Google Drive",
            "version": "1.0.0",
            "auth": {
              "mode": "oauth",
              "provider": "google-drive",
              "requiredScopes": [
                "https://www.googleapis.com/auth/drive"
              ]
            },
            "configFields": [
              {
                "id": "adminEmail",
                "title": "Crawl as",
                "type": "short-input",
                "placeholder": "admin@yourcompany.com",
                "required": false,
                "description": "The Google Workspace user this service account acts as when fetching content for connected members."
              },
              {
                "id": "userEmails",
                "title": "Users",
                "type": "short-input",
                "placeholder": "All active Google Workspace users",
                "required": false,
                "description": "Optional primary email addresses, separated by commas (up to 100). Leave blank to index all active users across this Google Workspace customer.",
                "multi": true
              },
              {
                "id": "openSharing",
                "title": "Openly shared files",
                "type": "dropdown",
                "placeholder": "Keep out of search",
                "required": false,
                "description": "Files shared beyond named people and groups. Kept out of search by default, because a domain-wide or public share is more often an accident than an intention. Never applies to link-only shares, which stay unsearchable.",
                "options": [
                  {
                    "label": "Keep out of search",
                    "id": "none"
                  },
                  {
                    "label": "Anyone in the domain can find",
                    "id": "domain"
                  },
                  {
                    "label": "Anyone can find",
                    "id": "anyone"
                  }
                ]
              },
              {
                "id": "folderSelector",
                "title": "Folders",
                "type": "selector",
                "placeholder": "Select one or more folders (optional)",
                "required": false,
                "description": "Includes files in each selected folder and its accessible subfolders.",
                "selectorKey": "google.drive",
                "mimeType": "application/vnd.google-apps.folder",
                "mode": "basic",
                "canonicalParamId": "folderId",
                "multi": true
              },
              {
                "id": "folderId",
                "title": "Folder IDs",
                "type": "short-input",
                "placeholder": "e.g. 1aBcDeFg…, 2cDeFgHi… (comma-separated for multiple)",
                "required": false,
                "description": "Includes files in each selected folder and its accessible subfolders.",
                "mode": "advanced",
                "canonicalParamId": "folderId",
                "multi": true
              },
              {
                "id": "fileType",
                "title": "File Type",
                "type": "dropdown",
                "required": false,
                "options": [
                  {
                    "label": "All supported files",
                    "id": "all"
                  },
                  {
                    "label": "Google Docs only",
                    "id": "documents"
                  },
                  {
                    "label": "Google Sheets only",
                    "id": "spreadsheets"
                  },
                  {
                    "label": "Google Slides only",
                    "id": "presentations"
                  },
                  {
                    "label": "Plain text files only",
                    "id": "text"
                  }
                ]
              },
              {
                "id": "maxFiles",
                "title": "Max Files",
                "type": "short-input",
                "placeholder": "e.g. 500 (default: unlimited)",
                "required": false
              }
            ],
            "supportsIncrementalSync": false,
            "tagDefinitions": [
              {
                "id": "owners",
                "displayName": "Owner",
                "fieldType": "text"
              },
              {
                "id": "fileType",
                "displayName": "File Type",
                "fieldType": "text"
              },
              {
                "id": "lastModified",
                "displayName": "Last Modified",
                "fieldType": "date"
              },
              {
                "id": "starred",
                "displayName": "Starred",
                "fieldType": "boolean"
              }
            ]
          }
        ],
        "nextCursor": null
      }
    ]
  },
  "#/components/schemas/V2ConnectorType": {
    "type": "object",
    "properties": {
      "connectorType": {
        "type": "string",
        "description": "Exact identifier to send when creating a connector of this type."
      },
      "name": {
        "type": "string",
        "description": "Display name."
      },
      "description": {
        "type": "string",
        "description": "What the connector syncs."
      },
      "version": {
        "type": "string",
        "description": "Connector version."
      },
      "auth": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "const": "oauth",
                "description": "Authenticates with an OAuth credential; pass `credentialId` when creating the connector."
              },
              "provider": {
                "type": "string",
                "description": "OAuth service the credential must authenticate."
              },
              "requiredScopes": {
                "description": "Scopes the credential must carry.",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "mode",
              "provider"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "const": "apiKey",
                "description": "Authenticates with a stored API key; pass `apiKey`, and no `credentialId`, when creating the connector."
              },
              "label": {
                "description": "Label shown above the key field.",
                "type": "string"
              },
              "placeholder": {
                "description": "Placeholder shown in the key field.",
                "type": "string"
              },
              "optional": {
                "type": "boolean",
                "description": "Whether the key may be left blank, for a source reachable without authentication."
              }
            },
            "required": [
              "mode",
              "optional"
            ],
            "additionalProperties": false
          }
        ],
        "description": "How the connector authenticates against its source: `oauth` connectors take `credentialId` (GitHub also accepts a personal access token as `apiKey`), `apiKey` connectors take `apiKey`."
      },
      "configFields": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/V2ConnectorConfigField"
        },
        "description": "Fields that make up the connector’s `sourceConfig`."
      },
      "supportsIncrementalSync": {
        "type": "boolean",
        "description": "Whether syncs after the first fetch only what changed."
      },
      "tagDefinitions": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Semantic tag identifier the connector populates."
            },
            "displayName": {
              "type": "string",
              "description": "Human-readable tag name."
            },
            "fieldType": {
              "type": "string",
              "enum": [
                "text",
                "number",
                "date",
                "boolean"
              ],
              "description": "Value type, which decides the tag slot pool it draws from."
            }
          },
          "required": [
            "id",
            "displayName",
            "fieldType"
          ],
          "additionalProperties": false
        },
        "description": "Tags this connector writes onto the documents it syncs."
      }
    },
    "required": [
      "connectorType",
      "name",
      "description",
      "version",
      "auth",
      "configFields",
      "supportsIncrementalSync",
      "tagDefinitions"
    ],
    "additionalProperties": false,
    "title": "Connector type",
    "description": "A knowledge-base connector type and the configuration it accepts."
  },
  "#/components/schemas/V2ConnectorConfigField": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Field identifier."
      },
      "title": {
        "type": "string",
        "description": "Human-readable label."
      },
      "type": {
        "type": "string",
        "enum": [
          "short-input",
          "dropdown",
          "selector"
        ],
        "description": "Control the field renders as. A `selector` fetches its options from the connected account."
      },
      "placeholder": {
        "description": "Placeholder shown in the editor.",
        "type": "string"
      },
      "required": {
        "description": "Whether a value must be supplied.",
        "type": "boolean"
      },
      "description": {
        "description": "Authored explanation of the field.",
        "type": "string"
      },
      "options": {
        "description": "Static options, for a `dropdown` field.",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "Value stored when this option is selected."
            },
            "label": {
              "type": "string",
              "description": "Human-readable option label."
            }
          },
          "required": [
            "id",
            "label"
          ],
          "additionalProperties": false
        }
      },
      "selectorKey": {
        "description": "Names the picker a `selector` field renders. Its options are fetched per workspace.",
        "type": "string"
      },
      "mimeType": {
        "description": "MIME type filter applied to the picker.",
        "type": "string"
      },
      "dependsOn": {
        "description": "Sibling fields this field is cleared by when they change.",
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "properties": {
              "all": {
                "description": "Every listed field must hold a value.",
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "any": {
                "description": "At least one listed field must hold a value.",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          }
        ]
      },
      "mode": {
        "description": "Which half of a canonical pair this field is: `basic` is the picker, `advanced` the manual entry.",
        "type": "string",
        "enum": [
          "basic",
          "advanced"
        ]
      },
      "canonicalParamId": {
        "description": "Shared `sourceConfig` key for a picker/manual-entry pair. Send exactly one of the pair, keyed by this value rather than by the field’s own `id`.",
        "type": "string"
      },
      "multi": {
        "description": "When true the stored `sourceConfig` value is a `string[]`, not a `string`: a `selector` renders a multi-select picker and a `short-input` accepts a comma-separated list.",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "title",
      "type"
    ],
    "additionalProperties": false,
    "title": "Connector config field",
    "description": "One field of a knowledge-base connector’s source configuration."
  },
  "#/components/schemas/V2ConnectorTypeSummary": {
    "type": "object",
    "properties": {
      "connectorType": {
        "type": "string",
        "description": "Exact identifier to send when creating a connector of this type."
      },
      "name": {
        "type": "string",
        "description": "Display name."
      },
      "description": {
        "type": "string",
        "description": "What the connector syncs."
      },
      "auth": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "oauth",
              "apiKey"
            ],
            "description": "How the connector authenticates against its source: `oauth` connectors take `credentialId` (GitHub also accepts a personal access token as `apiKey`), `apiKey` connectors take `apiKey`."
          }
        },
        "required": [
          "mode"
        ],
        "additionalProperties": false,
        "description": "Authentication mode only. `detail=full` adds the OAuth provider and scopes, or the API-key field labels."
      }
    },
    "required": [
      "connectorType",
      "name",
      "description",
      "auth"
    ],
    "additionalProperties": false,
    "title": "Connector type summary",
    "description": "A knowledge-base connector type without its configuration schema. Request `detail=full` for the config fields and tag definitions."
  },
  "#/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/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 `listConnectorTypes`.