Connectors

Understand the live connector catalogue, authorization methods, support levels, discovery, and sync behavior.

Connectors turn an external system into a governed Combined Source. The connector catalogue is live: use the Add Source flow or GET /v1/connector-definitions instead of relying on a static list in application code.

Connector definition

Every definition includes a stable key, revision, display metadata, category, support level, authorization type, credential schema, capabilities, and known limits. Treat the credential schema as the source of truth for the fields required by that revision.

Field	Meaning
`support`	`ready`, `preview`, or `planned` availability
`authorizationType`	`oauth2`, `credentials`, or `enrollment`
`credentialSchema`	JSON Schema used to collect and validate configuration
`capabilities`	Operations supported by the connector, such as check and discover
`knownLimits`	Connector-specific operational constraints

Filter the public catalogue when you only want a particular support level:

curl -fsS "$COMBINED_API_URL/v1/connector-definitions?support=ready" \
  -H "Authorization: Bearer $COMBINED_TOKEN"

Authorization patterns

OAuth connectors redirect a human to the provider and return to Combined. Credential connectors collect the fields declared by the connector's credential schema. Enrollment is used by the Combined Desktop app and binds a particular installation to its Source.

Credentials are secrets. Enter them only in the product authorization flow, never in SQL, logs, source names, agent prompts, or committed configuration. To delegate authorization, create a time-bounded authorization request for a recipient rather than forwarding credentials.

Connection lifecycle

Select a connector and name the Source.
Authorize it directly or send an authorization request.
Combined checks the configuration and discovers available datasets.
Select the datasets to ingest and review the resulting schema.
The first run is queued; later runs follow the Source schedule.

A Source can be healthy, syncing, needs_authorization, needs_review, paused, failed, deleting, or deleted. See Sources and freshness for the recovery action for each state.

Discovery, datasets, and schema changes

Discovery reads metadata from the provider and produces datasets and fields. It does not make every discovered field queryable automatically: material schema changes can enter needs_review until an owner accepts or rejects them. An accepted revision becomes the active logical catalogue; rejecting it preserves the last accepted revision.

Dataset sync modes are connector-dependent:

incremental_keyed advances a provider cursor or key.
append_only writes new observations without updating previous rows.
full_refresh replaces the dataset snapshot on each successful run.

Schedules can be manual, daily, or hourly. Hourly availability depends on connector policy and plan. Manual runs can be queued from the Source page or API.

Choosing a connector safely

Only ready definitions enter the authorization and connection flow. Selecting a preview definition records a request for bounded evaluation without collecting credentials. planned definitions are visible for discovery but cannot be connected. Review known limits before connecting any definition that is promoted to Ready.

The selected connector revision is part of Source provenance. Combined keeps the definition revision, configuration revision, schema revision, run, and committed snapshot distinct so an answer can be traced to the exact ingestion state that produced it.

API operations

GET /v1/connector-definitions lists definitions.
POST /v1/source-authorization-requests creates a delegated request before a Source is authorized.
GET /v1/source-authorization-requests/{requestId} reports authorization and discovery state.
POST /v1/sources/{sourceId}/authorization-requests reauthorizes an existing Source.

See Source operations for SDK equivalents and the endpoint reference for exact schemas.