Pragence

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:

PropertyTypeDescription
typestringValue to send as connector_type
namestringDisplay name
summarystringOne-line description
authstringnone, api_key, service_account or oauth2 (a sign-in flow; see Sign-in connections)
providerstring | nullFor oauth2: the sign-in provider (google, microsoft or atlassian)
deliverystringsynced (content is copied and kept current) or live
credentialsarrayField specs for credentials
settingsarrayField specs for settings
capabilitiesobjectincremental, deletions, permissions (booleans)
freshness_target_hoursintegerHow old the last successful sync may be before the source reads as behind
default_schedulestring | nullSuggested cron expression
productstring | nullProduct 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.

PropertyTypeRequiredDescription
connector_typestring*A type from GET /connectors/types
namestring*Display name
descriptionstringOptional description
collection_idstringCollection the documents are synced into
enabledbooleanDefault true
schedulestringCron expression, evaluated in UTC
credentialsobjectKeys from the type's credentials field specs
settingsobjectKeys from the type's settings field specs
connection_idstringA sign-in connection, for types whose auth is oauth2

Returns {"connector_id": "...", "message": "..."} in data.

Errors:

  • 400 with detail.error = "invalid_configuration" when a required field is missing, or when an oauth2 type has neither a connection_id nor a pasted credential it accepts.
  • 400 with detail.error = "not_configured" when connection_id is not a connection of the caller's organization.
  • 400 with detail.error = "invalid_schedule" when schedule is not a valid cron expression.
  • 403 when a non-admin sets settings.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:

PropertyDescription
id, connector_type, type_name, name, descriptionIdentity
org_id, collection_idWhere it belongs
enabled, schedule, settingsConfiguration (no credentials)
created_at, updated_atTimestamps
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_reasonnull, paused_by_operator or repeated_failures
consecutive_failuresFailed syncs in a row
next_run_atNext 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_countTotals
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.status to unchecked.
  • Changing settings.mirror_permissions needs an organization admin (403 otherwise).
  • An invalid schedule returns 400 with detail.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.

PropertyTypeRequiredDescription
sincedatetimeOnly documents modified after this time. Default: the start of the last applied sync
limitintegerMaximum 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}.

On this page