Connect a knowledge source
Connect a knowledge source to one container in a registered provider’s system, writing to a scope in your writable namespaces. Requires knowledge:manage and credentials:use.
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.
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.
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
Headers
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.
1 - 255Body
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.
Response
The source connected
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.

