Connectors API
A connector is one configured knowledge source for an organization. Every sync is recorded as a run; progress, per-document outcomes, retry and cancel are in the Ingestion runs API.
All routes need an authenticated organization member unless a route says admin.
Creating, updating, syncing and approving also need the Knowledge product grant
and write access to the destination collection, the same as an upload; 403
otherwise.
Responses use the envelope {"success": true, "data": ...}.
Connector types
GET /api/v1/connectors/types
Every connector type that can be created in this deployment. Clients render the connect form from this response.
Each entry in data has:
| Property | Type | Description |
|---|---|---|
type | string | Value to send as connector_type |
name | string | Display name |
summary | string | One-line description |
auth | string | none, api_key, service_account or oauth2 (a sign-in flow; see Sign-in connections) |
provider | string | null | For oauth2: the sign-in provider (google, microsoft or atlassian) |
delivery | string | synced (content is copied and kept current) or live |
credentials | array | Field specs for credentials |
settings | array | Field specs for settings |
capabilities | object | incremental, deletions, permissions (booleans) |
freshness_target_hours | integer | How old the last successful sync may be before the source reads as behind |
default_schedule | string | null | Suggested cron expression |
product | string | null | Product the type is for; null means shared Knowledge |
A field spec has key, label, kind (text, secret, url, number,
boolean, list or json), required, placeholder, help and default.
The eight workplace tool types
(dlt:slack, dlt:jira and so on) are always in the list. When ENABLE_DLT
is on, the generic dlt:sql_database, dlt:rest_api and dlt:filesystem
types are appended; those also carry available and install_hint.
Create and manage
POST /api/v1/connectors/
Create a connector.
| Property | Type | Required | Description |
|---|---|---|---|
connector_type | string | * | A type from GET /connectors/types |
name | string | * | Display name |
description | string | Optional description | |
collection_id | string | Collection the documents are synced into | |
enabled | boolean | Default true | |
schedule | string | Cron expression, evaluated in UTC | |
credentials | object | Keys from the type's credentials field specs | |
settings | object | Keys from the type's settings field specs | |
connection_id | string | A sign-in connection, for types whose auth is oauth2 |
Returns {"connector_id": "...", "message": "..."} in data.
Errors:
400withdetail.error = "invalid_configuration"when a required field is missing, or when anoauth2type has neither aconnection_idnor a pasted credential it accepts.400withdetail.error = "not_configured"whenconnection_idis not a connection of the caller's organization.400withdetail.error = "invalid_schedule"whenscheduleis not a valid cron expression.403when a non-admin setssettings.mirror_permissions.
Credentials are stored encrypted and are never returned.
GET /api/v1/connectors/
List the organization's connectors. Query: enabled_only (boolean, default
false).
Each connector in data has:
| Property | Description |
|---|---|
id, connector_type, type_name, name, description | Identity |
org_id, collection_id | Where it belongs |
enabled, schedule, settings | Configuration (no credentials) |
created_at, updated_at | Timestamps |
connection | {status, error, checked_at, connection_id, signed_in_as}; status is unchecked, connected, needs_attention or not_required. A sign-in source whose sign-in is missing or was refused reads needs_attention |
paused_reason | null, paused_by_operator or repeated_failures |
consecutive_failures | Failed syncs in a row |
next_run_at | Next scheduled sync, or null when unscheduled or paused |
freshness | {status, target_hours, last_success_at}; status is fresh, behind, stale or manual |
permissions | {mirrored, confirmed_at} |
document_count, sync_count | Totals |
last_run | {id, status, trigger, created_at, completed_at, failed, reason_code, error_message, detail} or null |
GET /api/v1/connectors/{connector_id}
One connector in the same shape, plus credentials_hint: which credential
fields are set, with values masked. Returns 404 if it does not exist and 403
if it belongs to another organization.
PATCH /api/v1/connectors/{connector_id}
Update name, description, enabled, schedule, credentials, settings,
collection_id or connection_id. All fields are optional.
- A credential field left out or sent empty keeps its stored value.
- New credentials reset
connection.statustounchecked. - Changing
settings.mirror_permissionsneeds an organization admin (403otherwise). - An invalid
schedulereturns400withdetail.error = "invalid_schedule".
DELETE /api/v1/connectors/{connector_id}
Delete the connector and its run history. Query: delete_documents (boolean,
default false). The documents it brought in are kept unless
delete_documents=true.
Connection
POST /api/v1/connectors/test
Check that a configuration can sign in to its source before creating a
connector. Body: connector_type (required), credentials, settings,
connection_id.
Returns {"ok": true|false, "error": string|null} in data. An unknown
connector_type returns 400.
POST /api/v1/connectors/{connector_id}/test
Check the stored sign-in and record the result on the connector
(connection.status becomes connected or needs_attention). Same response as
above.
POST /api/v1/connectors/{connector_id}/pause
Stop scheduled syncs. Indexed content stays searchable and manual syncs still
work. Returns {"paused": true}.
POST /api/v1/connectors/{connector_id}/resume
Resume scheduled syncs and clear the failure count. Returns {"paused": false}.
A connector is paused automatically (paused_reason = "repeated_failures")
after three failed syncs in a row. A later successful sync clears that pause.
Sync
POST /api/v1/connectors/{connector_id}/sync
Start a sync. Returns 202.
| Property | Type | Required | Description |
|---|---|---|---|
since | datetime | Only documents modified after this time. Default: the start of the last applied sync | |
limit | integer | Maximum documents to fetch. A limited sync does not remove deleted documents |
Response data:
{
"sync_id": "<run-id>",
"connector_id": "<connector-id>",
"status": "queued",
"status_url": "/api/v1/ingestion/runs/<run-id>",
"message": "Sync accepted; poll status_url for progress."
}sync_id is an ingestion run id. Poll status_url.
Errors: 402 when the organization lacks credits, 403 when the caller may
not write to the destination, 503 with detail.code = "billing_catalogue_unconfigured" when the deployment has no rate configured
for syncs (a fresh install, until an operator applies the billing catalogue),
404 for an unknown connector, 409 when a sync for this connector is already queued or running.
Credits are charged after a sync that applied; a failed or held sync is not
charged.
POST /api/v1/connectors/{connector_id}/sync/approve
Approve a sync that ended held_for_review by running it again with the
large-change check bypassed. Returns 202 with the same body as /sync. No
additional credits are charged. 409 when a sync is already queued or running.
Permission refresh
POST /api/v1/connectors/{connector_id}/permissions/refresh
Re-read who can see each document already indexed, without re-reading content.
Only for a source that mirrors sharing (mirror_permissions on a type with the
permissions capability); 409 otherwise, and 409 while a sync or refresh is
queued or running. Returns 202 with {run_id, status, status_url}; the run has
kind permissions. Not charged. The same refresh starts on its own every six
hours for a mirroring source whose sharing has not been confirmed in that time,
well inside the 24 hours after which unconfirmed documents are hidden.
Access groups
Used with Google Drive, SharePoint/OneDrive and Confluence permission mirroring. Both routes need an organization admin.
GET /api/v1/connectors/{connector_id}/access-groups
Returns {"groups": {"<group email>": ["<member email>", ...]}, "groups_without_members": ["<group email>", ...]}
in data. groups_without_members lists groups that documents are shared with
but that have no members supplied.
PUT /api/v1/connectors/{connector_id}/access-groups
Replace the connector's group memberships.
{"groups": {"eng@example.com": ["ana@example.com", "li@example.com"]}}Returns {"groups": <count>, "memberships": <count>}. A group with no members
listed grants nobody access.
Sign-in connections
Types whose auth is oauth2 (Google Drive, SharePoint and OneDrive,
Confluence) read through a connection: the tokens a provider returned after an
operator signed in. Tokens are stored encrypted, refreshed before they expire
and never returned by any route. These routes return plain JSON, without the
success/data envelope.
Each deployment registers its own app with the provider and sets
SOURCE_<PROVIDER>_CLIENT_ID and SOURCE_<PROVIDER>_CLIENT_SECRET
(GOOGLE, MICROSOFT, ATLASSIAN; SOURCE_MICROSOFT_TENANT defaults to
common). The redirect address to register is
{OAUTH_REDIRECT_BASE_URL}/api/v1/connections/{provider}/callback.
GET /api/v1/connections/providers
{"providers": [{"key": "google", "name": "Google", "configured": true}]}.
A provider without a client id and secret has configured: false.
GET /api/v1/connections/
{"connections": [...]}. Each has id, provider, account_label, scopes,
status (connected or needs_attention), error, expires_at,
created_at and source_count.
POST /api/v1/connections/{provider}/authorize
Body: return_to (a console path; default /manage/sources/new). Returns
{"authorize_url": "..."}, valid for ten minutes. Send the operator's browser
there. 400 with detail.error = "not_configured" when the provider is unknown
or not set up.
After the operator approves, the provider returns them to the callback, which
redirects to return_to on the console with connection_id and provider in
the query, or with sign_in_error. Pass connection_id when creating the
connector.
DELETE /api/v1/connections/{connection_id}
Forget a connection's tokens. Returns {"deleted": true}, or 404. Sources
using it stop syncing until someone signs in again.
Removed routes
GET /api/v1/connectors/{connector_id}/syncs and
GET /api/v1/connectors/{connector_id}/syncs/{sync_id} no longer exist. Use
GET /api/v1/ingestion/runs?connector_id=... and
GET /api/v1/ingestion/runs/{run_id}.