Skip to main content
POST
Connect a knowledge source
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/knowledge/synchronized-sources/create connects a source, as Add source does on the Console Knowledge › Synchronized sources page. It answers 201 with the KnowledgeSource that Get a knowledge source returns. MCP hosts call it through forge_call_operation with operationId createSynchronizedSource. It needs both knowledge:manage and credentials:use, and the credential’s scopes must reach both. A source never stores a credential: it syncs with the credential on its vendor’s connection that resolves along its target scope, so connecting one uses that credential. A credential missing either permission answers 403 permission_denied naming it, recorded. The target must be in the caller’s writable namespaces (see Scope resolution): for an External App, its own external_app namespace and the factory, project and team namespaces of its owner chain, and company for every caller, since this route requires knowledge:manage. A department or global namespace is never writable through the API. A target outside the writable set answers 403 forbidden, recorded, and writes nothing. The source is created by, and audited as, the credential. The required stored mode and current source response accept only synchronize; a new source is due to sync at once. Retired modes are refused before a source write. The response never carries the source’s configuration, external container id, curation, trust weight or creator. Send an Idempotency-Key to retry safely: a repeat connects nothing again. It returns the recorded 201 only while the credential still holds knowledge:read and the created source is still in its writable namespaces; otherwise it answers 403 for a missing knowledge:read, or 409 idempotency_result_unavailable. See Knowledge source replay.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters. A repeat with the same key and request never runs the write again, a 5xx included. It returns the first response (Idempotency-Replayed: true) only when the route's current authorization policy permits disclosure; otherwise 409 idempotency_result_unavailable. Honoured for External App JWTs and platform and MCP keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Body

application/json

A source to connect: a registered provider (synchronized-sources/listProviders), one container in its system, and the scope it writes to, which must be in the caller's writable namespaces (a department never is). curated defaults to false. mode defaults to synchronize, which copies the source's records in on a schedule; only synchronized sources can be connected. config holds non-secret provider settings only: a secret-shaped key or value is refused, because a source syncs with the credential on its vendor's connection that resolves along its target scope.

name
string
required
Minimum string length: 1
providerKey
string
required
Minimum string length: 1
externalContainerId
string
required
Minimum string length: 1
targetScopeType
enum<string>
required
Available options:
company,
department,
team,
factory,
project
syncIntervalMinutes
number
required
config
object
targetScopeEntityId
string
Minimum string length: 1
curated
boolean
mode
string
Allowed value: "synchronize"

Response

The source connected

data
object
required

One knowledge source in a namespace the caller can read: what it connects to (by provider), where it writes, whether it is active, paused or failing, and when it last and next syncs. lastError is redacted. Its configuration, cursor, external container id, identity and group mappings, curation, trust weight and creator are never returned.

meta
object
required