Sources API

11 operations. Paths are relative to the API host (http://localhost:5080 in local development). Every operation accepts an OIDC bearer token (Authorization: Bearer …) or a workspace API key (X-Api-Key: keel_live_…); errors are RFC 9457 Problem Details with a code (error codes). Permissions: matrix.

Method	Path	Summary
GET	/api/v1/connection-schemas	Source kinds and the fields of their connect wizard (F02).
GET	/api/v1/workspaces/{workspaceId}/sources	Data sources of a workspace.
POST	/api/v1/workspaces/{workspaceId}/sources	Register a data source. The secret goes to the secret store; only a reference is kept.
GET	/api/v1/workspaces/{workspaceId}/sources/{sourceId}	One data source with its last Test connection checklist (never the secret).
PUT	/api/v1/workspaces/{workspaceId}/sources/{sourceId}	Change connection details, scope or profiling policy.
DELETE	/api/v1/workspaces/{workspaceId}/sources/{sourceId}	Delete a data source (soft delete, audited; its secret is destroyed).
POST	/api/v1/workspaces/{workspaceId}/sources/{sourceId}:test	Queue Test connection; the checklist is stored on the source when the job completes.
PUT	/api/v1/workspaces/{workspaceId}/sources/{sourceId}/drift-schedule	When drift scans run for the source (F16; five-field cron, UTC), or turn them off.
PUT	/api/v1/workspaces/{workspaceId}/sources/{sourceId}/secret	Replace the password or key (write-only).
GET	/api/v1/workspaces/{workspaceId}/sources/sample	Whether this deployment offers the sample warehouse (F21 onboarding), and the workspace's sample source if added.
POST	/api/v1/workspaces/{workspaceId}/sources/sample	Add the read-only sample warehouse as a source (F21 'Explore with sample data'); idempotent. Start its scan with ScanDataSource.

ListConnectionSchemas

GET /api/v1/connection-schemas

Source kinds and the fields of their connect wizard (F02).

Status	Description	Body
200	OK	ConnectionSchemaDto[]

ListDataSources

GET /api/v1/workspaces/{workspaceId}/sources

Data sources of a workspace.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
page	query	int32	no
pageSize	query	int32	no

Status	Description	Body
200	OK	PagedResultOfDataSourceSummary

Response 200: PagedResultOfDataSourceSummary

Field	Type	Notes
hasNext	boolean
items	DataSourceSummary[]
page	int32
pageSize	int32
totalCount	int64

RegisterDataSource

POST /api/v1/workspaces/{workspaceId}/sources

Register a data source. The secret goes to the secret store; only a reference is kept.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Request body (application/json): RegisterDataSourceRequest

Field	Type	Notes
agentId	uuid?	PrivateAgent mode: the agent the source connects through (ADR-0006).
agentPool	string?	PrivateAgent mode (F22): an agent pool instead of one agent; any healthy agent of the pool runs the work.
agentSecretName	string?	PrivateAgent mode: the name of the secret in the agent's local secret store (the value never reaches Keel).
database	string
exclude	string[]?
host	string
include	string[]?
kind	SourceKind	One of PostgreSql, SqlServer, MySql, Snowflake, BigQuery, Databricks, Oracle, Redshift
name	string
networkMode	NetworkMode	One of Direct, PrivateAgent
options	object?
port	int32?
profiling	ProfilingPolicyDto?
secret	string	Password / key / service-account JSON. Write-only: never returned by any endpoint (F02 FR3). Empty for private-agent sources.
username	string

Status	Description	Body
201	Created	CreatedResponse

Response 201: CreatedResponse

Field	Type	Notes
id	uuid

GetDataSource

GET /api/v1/workspaces/{workspaceId}/sources/{sourceId}

One data source with its last Test connection checklist (never the secret).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Status	Description	Body
200	OK	DataSourceDetail

Response 200: DataSourceDetail

Field	Type	Notes
agentId	uuid?
agentPool	string?
agentSecretName	string?
createdAt	date-time
database	string
driftSchedule	DriftScheduleDto
exclude	string[]
hasSecret	boolean
host	string
id	uuid
include	string[]
kind	SourceKind	One of PostgreSql, SqlServer, MySql, Snowflake, BigQuery, Databricks, Oracle, Redshift
lastChecks	ConnectionCheckDto[]
lastScanAt	date-time?
lastScanError	string?
lastScanStatus	string?
lastTestedAt	date-time?
name	string
networkMode	NetworkMode	One of Direct, PrivateAgent
options	object
port	int32?
profiling	ProfilingPolicyDto
status	DataSourceStatus	One of Untested, Healthy, Degraded, Failing
tablesInScope	int32?
username	string
workspaceId	uuid

UpdateDataSource

PUT /api/v1/workspaces/{workspaceId}/sources/{sourceId}

Change connection details, scope or profiling policy.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Request body (application/json): UpdateDataSourceRequest

Field	Type	Notes
agentId	uuid?
agentPool	string?
agentSecretName	string?
database	string
exclude	string[]?
host	string
include	string[]
name	string
networkMode	NetworkMode	One of Direct, PrivateAgent
options	object?
port	int32?
profiling	ProfilingPolicyDto?
username	string

Status	Description	Body
204	No Content	—

DeleteDataSource

DELETE /api/v1/workspaces/{workspaceId}/sources/{sourceId}

Delete a data source (soft delete, audited; its secret is destroyed).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Status	Description	Body
204	No Content	—

TestDataSource

POST /api/v1/workspaces/{workspaceId}/sources/{sourceId}:test

Queue Test connection; the checklist is stored on the source when the job completes.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Status	Description	Body
202	Accepted	JobAccepted

Response 202: JobAccepted

Field	Type	Notes
jobId	uuid

SetDriftSchedule

PUT /api/v1/workspaces/{workspaceId}/sources/{sourceId}/drift-schedule

When drift scans run for the source (F16; five-field cron, UTC), or turn them off.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Request body (application/json): DriftScheduleRequest

Field	Type	Notes
cron	string	Five-field cron, UTC (e.g. 0 3 * * *, daily at 03:00).
enabled	boolean

Status	Description	Body
204	No Content	—

RotateDataSourceSecret

PUT /api/v1/workspaces/{workspaceId}/sources/{sourceId}/secret

Replace the password or key (write-only).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	path	uuid	yes

Request body (application/json): RotateSecretRequest

Field	Type	Notes
secret	string

Status	Description	Body
204	No Content	—

GetSampleSource

GET /api/v1/workspaces/{workspaceId}/sources/sample

Whether this deployment offers the sample warehouse (F21 onboarding), and the workspace's sample source if added.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
200	OK	SampleSourceStatus

Response 200: SampleSourceStatus

Field	Type	Notes
available	boolean
name	string?
sourceId	uuid?

RegisterSampleSource

POST /api/v1/workspaces/{workspaceId}/sources/sample

Add the read-only sample warehouse as a source (F21 'Explore with sample data'); idempotent. Start its scan with ScanDataSource.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
201	Created	CreatedResponse

Response 201: CreatedResponse

Field	Type	Notes
id	uuid