Skip to content
Try for free
On this page

Knowledge bases

Create knowledge connector

Validate and connect an external source, then queue its initial synchronization. The `apiKey` field is never returned. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:write`.

POST/api/v2/knowledge/{knowledgeBaseId}/connectors

Validate and connect an external source, then queue its initial synchronization. The apiKey field is never returned. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows
json
{
  "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"
    }
  }
}

OAuth scope: api:write.

Path parameters

knowledgeBaseIdstringRequired

Unique knowledge base identifier.

minLength
1

Request body

Required

Workspace, connector type, authentication reference, source configuration, and sync schedule.

object

Workspace, connector type, authentication reference, source configuration, and sync schedule.

6 fields
workspaceIdstringRequired

Workspace that owns the knowledge base.

minLength
1
maxLength
128
connectorTypestringRequired

Registered connector type.

minLength
1
maxLength
100
credentialIdstring

OAuth credential identifier for connector types whose auth.mode is oauth (see connector types); omit it for apiKey connectors.

minLength
1
maxLength
255
apiKeystring

Write-only API key for connector types whose auth.mode is apiKey (see connector types), or a personal access token for an OAuth connector that also accepts one, such as GitHub. Send it instead of credentialId. Pass a raw key, or a secret reference written as the whole value {{SECRET_NAME}}, which the server resolves; $SECRET_NAME is not a reference.

minLength
1
maxLength
10000
sourceConfigobjectRequired

Connector-specific source selection and filtering configuration.

Schema details
Additional propertiesvalue

Connector-specific source configuration value.

syncIntervalMinutesinteger

Scheduled synchronization interval in minutes; zero disables scheduling.

default
1440
minimum
0
maximum
525600

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "connectorType": "notion",
  "credentialId": "cred-4b3a2c1d",
  "sourceConfig": {
    "pageIds": [
      "page-123"
    ]
  },
  "syncIntervalMinutes": 1440
}

Responses

201

The created connector without secret material.

object

A single connector without secret material.

1 field
dataobjectRequired

Response data.

15 fields
idstringRequired

Unique connector identifier.

minLength
1
knowledgeBaseIdstringRequired

Knowledge base synced by the connector.

minLength
1
connectorTypestringRequired

Registered external source type.

minLength
1
credentialIdvalueRequired

OAuth credential identifier, or null for API-key and unauthenticated sources.

Schema details

Any of

Option 1string
Option 2null
sourceConfigobjectRequired

Connector-specific source selection and filtering configuration.

Schema details
Additional propertiesvalue

Connector-specific source configuration value.

syncModestringRequired

Synchronization mode used by the connector.

syncIntervalMinutesintegerRequired

Scheduled synchronization interval in minutes; zero disables scheduled syncs.

minimum
0
maximum
9007199254740991
statusstringRequired

Current connector state. pending means a sync is queued but not yet running.

enum
["active","paused","pending","syncing","error","disabled"]
lastSyncAtvalueRequired

Time of the most recent synchronization, or null before the first sync.

Schema details

Any of

Option 1string
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))$
Option 2null
lastSyncErrorvalueRequired

Most recent synchronization error, or null when none is recorded.

Schema details

Any of

Option 1string
Option 2null
lastSyncDocCountvalueRequired

Documents observed by the most recent synchronization.

Schema details

Any of

Option 1integer
minimum
0
maximum
9007199254740991
Option 2null
nextSyncAtvalueRequired

Next scheduled synchronization time, or null when not scheduled.

Schema details

Any of

Option 1string
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))$
Option 2null
consecutiveFailuresintegerRequired

Number of consecutive synchronization failures.

minimum
0
maximum
9007199254740991
createdAtstringRequired

Time the connector was created.

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))$
updatedAtstringRequired

Time the connector was last updated.

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))$

Additional properties are not allowed.

Additional properties are not allowed.

Response example 1

json
{
  "data": {
    "id": "kc-9f8e7d6c",
    "knowledgeBaseId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "connectorType": "notion",
    "credentialId": "cred-4b3a2c1d",
    "sourceConfig": {
      "pageIds": [
        "page-123"
      ]
    },
    "syncMode": "full",
    "syncIntervalMinutes": 1440,
    "status": "active",
    "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:02:11.000Z"
  }
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

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))$
Was this helpful?
Suggest an edit