# Update knowledge connector (/api-reference/knowledge-bases/updateKnowledgeConnector)

`PATCH /api/v2/knowledge/{knowledgeBaseId}/connectors/{connectorId}`

Update connector source configuration, schedule, or active state. Replacing source configuration on a runnable connector queues an immediate synchronization; paused connectors retain the change without synchronizing until resumed. Source configuration cannot be replaced while synchronization is already in progress. Authentication material cannot be changed through this operation. 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 PATCH 'https://www.sim.ai/api/v2/knowledge/string/connectors/string' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "status": "paused"
}'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/knowledge/string/connectors/string", {
  "method": "PATCH",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"status\": \"paused\"\n}"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "PATCH",
    "https://www.sim.ai/api/v2/knowledge/string/connectors/string",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"status\": \"paused\"\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("PATCH", "https://www.sim.ai/api/v2/knowledge/string/connectors/string", strings.NewReader("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"status\": \"paused\"\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/knowledge/string/connectors/string"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"status\": \"paused\"\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("PATCH"), "https://www.sim.ai/api/v2/knowledge/string/connectors/string");
request.Content = new StringContent("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"status\": \"paused\"\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": "connectorId",
    "in": "path",
    "required": true,
    "description": "Connector selected for the operation.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Connector selected for the operation."
    }
  },
  {
    "name": "knowledgeBaseId",
    "in": "path",
    "required": true,
    "description": "Knowledge base that owns the connector.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "description": "Knowledge base that owns the connector."
    }
  }
]

```

## Request body

```json

{
  "required": true,
  "description": "Workspace scope and at least one mutable connector field.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "workspaceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Workspace that owns the knowledge base."
          },
          "sourceConfig": {
            "description": "Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "description": "Connector-specific source configuration value."
            }
          },
          "syncIntervalMinutes": {
            "description": "New scheduled synchronization interval in minutes.",
            "type": "integer",
            "minimum": 0,
            "maximum": 525600
          },
          "status": {
            "description": "New connector state.",
            "type": "string",
            "enum": [
              "active",
              "paused"
            ]
          }
        },
        "required": [
          "workspaceId"
        ],
        "additionalProperties": false,
        "title": "Update knowledge connector request",
        "description": "Workspace scope and at least one mutable connector field.",
        "examples": [
          {
            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
            "status": "paused"
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Request example 1",
          "value": {
            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
            "status": "paused"
          }
        }
      }
    }
  }
}

```

## Responses

### 200

```json

{
  "description": "The updated connector.",
  "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,
                "description": "Unique connector identifier."
              },
              "knowledgeBaseId": {
                "type": "string",
                "minLength": 1,
                "description": "Knowledge base synced by the connector."
              },
              "connectorType": {
                "type": "string",
                "minLength": 1,
                "description": "Registered external source type."
              },
              "credentialId": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "OAuth credential identifier, or null for API-key and unauthenticated sources."
              },
              "sourceConfig": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "description": "Connector-specific source configuration value."
                },
                "description": "Connector-specific source selection and filtering configuration."
              },
              "syncMode": {
                "type": "string",
                "description": "Synchronization mode used by the connector."
              },
              "syncIntervalMinutes": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "paused",
                  "pending",
                  "syncing",
                  "error",
                  "disabled"
                ],
                "description": "Current connector state. `pending` means a sync is queued but not yet running."
              },
              "lastSyncAt": {
                "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": "Time of the most recent synchronization, or null before the first sync."
              },
              "lastSyncError": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Most recent synchronization error, or null when none is recorded."
              },
              "lastSyncDocCount": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Documents observed by the most recent synchronization."
              },
              "nextSyncAt": {
                "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": "Next scheduled synchronization time, or null when not scheduled."
              },
              "consecutiveFailures": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991,
                "description": "Number of consecutive synchronization failures."
              },
              "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": "Time the connector was created."
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                "description": "Time the connector was last updated."
              }
            },
            "required": [
              "id",
              "knowledgeBaseId",
              "connectorType",
              "credentialId",
              "sourceConfig",
              "syncMode",
              "syncIntervalMinutes",
              "status",
              "lastSyncAt",
              "lastSyncError",
              "lastSyncDocCount",
              "nextSyncAt",
              "consecutiveFailures",
              "createdAt",
              "updatedAt"
            ],
            "additionalProperties": false,
            "title": "Knowledge connector",
            "description": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Update knowledge connector response",
        "description": "A single connector without secret material.",
        "examples": [
          {
            "data": {
              "id": "kc-9f8e7d6c",
              "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
              "connectorType": "notion",
              "credentialId": "cred-4b3a2c1d",
              "sourceConfig": {
                "pageIds": [
                  "page-123"
                ]
              },
              "syncMode": "full",
              "syncIntervalMinutes": 1440,
              "status": "paused",
              "lastSyncAt": "2026-06-20T14:02:11.000Z",
              "lastSyncError": null,
              "lastSyncDocCount": 42,
              "nextSyncAt": "2026-06-21T14:02:11.000Z",
              "consecutiveFailures": 0,
              "createdAt": "2026-06-01T09:14:00.000Z",
              "updatedAt": "2026-06-20T14:03:00.000Z"
            }
          }
        ]
      },
      "examples": {
        "example1": {
          "summary": "Response example 1",
          "value": {
            "data": {
              "id": "kc-9f8e7d6c",
              "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
              "connectorType": "notion",
              "credentialId": "cred-4b3a2c1d",
              "sourceConfig": {
                "pageIds": [
                  "page-123"
                ]
              },
              "syncMode": "full",
              "syncIntervalMinutes": 1440,
              "status": "paused",
              "lastSyncAt": "2026-06-20T14:02:11.000Z",
              "lastSyncError": null,
              "lastSyncDocCount": 42,
              "nextSyncAt": "2026-06-21T14:02:11.000Z",
              "consecutiveFailures": 0,
              "createdAt": "2026-06-01T09:14:00.000Z",
              "updatedAt": "2026-06-20T14:03:00.000Z"
            }
          }
        }
      }
    }
  }
}

```

### 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 current knowledge resource state"
        }
      }
    }
  }
}

```

### 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/UpdateKnowledgeConnectorRequest": {
    "type": "object",
    "properties": {
      "workspaceId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "description": "Workspace that owns the knowledge base."
      },
      "sourceConfig": {
        "description": "Replacement source selection and filtering configuration. Updating a runnable connector queues synchronization; paused connectors remain paused.",
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "description": "Connector-specific source configuration value."
        }
      },
      "syncIntervalMinutes": {
        "description": "New scheduled synchronization interval in minutes.",
        "type": "integer",
        "minimum": 0,
        "maximum": 525600
      },
      "status": {
        "description": "New connector state.",
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      }
    },
    "required": [
      "workspaceId"
    ],
    "additionalProperties": false,
    "title": "Update knowledge connector request",
    "description": "Workspace scope and at least one mutable connector field.",
    "examples": [
      {
        "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
        "status": "paused"
      }
    ]
  },
  "#/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/UpdateKnowledgeConnectorResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2KnowledgeConnector"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Update knowledge connector response",
    "description": "A single connector without secret material.",
    "examples": [
      {
        "data": {
          "id": "kc-9f8e7d6c",
          "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "connectorType": "notion",
          "credentialId": "cred-4b3a2c1d",
          "sourceConfig": {
            "pageIds": [
              "page-123"
            ]
          },
          "syncMode": "full",
          "syncIntervalMinutes": 1440,
          "status": "paused",
          "lastSyncAt": "2026-06-20T14:02:11.000Z",
          "lastSyncError": null,
          "lastSyncDocCount": 42,
          "nextSyncAt": "2026-06-21T14:02:11.000Z",
          "consecutiveFailures": 0,
          "createdAt": "2026-06-01T09:14:00.000Z",
          "updatedAt": "2026-06-20T14:03:00.000Z"
        }
      }
    ]
  },
  "#/components/schemas/V2KnowledgeConnector": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "description": "Unique connector identifier."
      },
      "knowledgeBaseId": {
        "type": "string",
        "minLength": 1,
        "description": "Knowledge base synced by the connector."
      },
      "connectorType": {
        "type": "string",
        "minLength": 1,
        "description": "Registered external source type."
      },
      "credentialId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "OAuth credential identifier, or null for API-key and unauthenticated sources."
      },
      "sourceConfig": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "description": "Connector-specific source configuration value."
        },
        "description": "Connector-specific source selection and filtering configuration."
      },
      "syncMode": {
        "type": "string",
        "description": "Synchronization mode used by the connector."
      },
      "syncIntervalMinutes": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Scheduled synchronization interval in minutes; zero disables scheduled syncs."
      },
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused",
          "pending",
          "syncing",
          "error",
          "disabled"
        ],
        "description": "Current connector state. `pending` means a sync is queued but not yet running."
      },
      "lastSyncAt": {
        "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": "Time of the most recent synchronization, or null before the first sync."
      },
      "lastSyncError": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Most recent synchronization error, or null when none is recorded."
      },
      "lastSyncDocCount": {
        "anyOf": [
          {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          {
            "type": "null"
          }
        ],
        "description": "Documents observed by the most recent synchronization."
      },
      "nextSyncAt": {
        "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": "Next scheduled synchronization time, or null when not scheduled."
      },
      "consecutiveFailures": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Number of consecutive synchronization failures."
      },
      "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": "Time the connector was created."
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
        "description": "Time the connector was last updated."
      }
    },
    "required": [
      "id",
      "knowledgeBaseId",
      "connectorType",
      "credentialId",
      "sourceConfig",
      "syncMode",
      "syncIntervalMinutes",
      "status",
      "lastSyncAt",
      "lastSyncError",
      "lastSyncDocCount",
      "nextSyncAt",
      "consecutiveFailures",
      "createdAt",
      "updatedAt"
    ],
    "additionalProperties": false,
    "title": "Knowledge connector",
    "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 current knowledge resource state"
          }
        }
      }
    }
  },
  "#/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-knowledge.json`, operation `updateKnowledgeConnector`.