Discovery API

13 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/workspaces/{workspaceId}/discovery-runs	Discovery runs of a workspace (or one source), newest first.
GET	/api/v1/workspaces/{workspaceId}/discovery-runs/{runId}	A discovery run with its stages and metrics.
POST	/api/v1/workspaces/{workspaceId}/discovery-runs/{runId}:cancel	Cancel a run; its source queries stop within seconds.
POST	/api/v1/workspaces/{workspaceId}/discovery-runs/{runId}:retry	Resume a failed or cancelled run from its first unfinished stage.
GET	/api/v1/workspaces/{workspaceId}/drift-events	Schema drift events of a workspace (or one source), newest first.
GET	/api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}	One schema drift event with its impact and the change request proposing the fix.
POST	/api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}:acknowledge	Acknowledge a drift event (it stays listed until resolved).
POST	/api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}:resolve	Resolve a drift event (fix merged, source reverted or change accepted).
GET	/api/v1/workspaces/{workspaceId}/snapshots/{snapshotId}/tables/{tableId}	A table with columns, profiles, keys, indexes and declared relationships.
GET	/api/v1/workspaces/{workspaceId}/snapshots/{snapshotId}/tree	Schemas and tables of a snapshot.
POST	/api/v1/workspaces/{workspaceId}/sources/{sourceId}:check-drift	Start a metadata-only drift scan compared with the last snapshot (F16). Progress: /jobs/{jobId}/events.
POST	/api/v1/workspaces/{workspaceId}/sources/{sourceId}:scan	Start a discovery run (harvest + profile). Progress: /jobs/{jobId}/events.
GET	/api/v1/workspaces/{workspaceId}/sources/{sourceId}/snapshots	Schema snapshots of a source, newest first.

ListDiscoveryRuns

GET /api/v1/workspaces/{workspaceId}/discovery-runs

Discovery runs of a workspace (or one source), newest first.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	query	uuid	no
limit	query	int32	no

Status	Description	Body
200	OK	DiscoveryRunDto[]

GetDiscoveryRun

GET /api/v1/workspaces/{workspaceId}/discovery-runs/{runId}

A discovery run with its stages and metrics.

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

Status	Description	Body
200	OK	DiscoveryRunDto

Response 200: DiscoveryRunDto

Field	Type	Notes
completedAt	date-time?
dataSourceId	uuid
dataSourceName	string
id	uuid
jobId	uuid?
requestedAt	date-time
snapshotId	uuid?
stages	StageDto[]
startedAt	date-time?
status	RunStatus	One of Queued, Running, Succeeded, Failed, Cancelling, Cancelled
trigger	RunTrigger	One of Manual, Scheduled, Drift
workspaceId	uuid

CancelDiscoveryRun

POST /api/v1/workspaces/{workspaceId}/discovery-runs/{runId}:cancel

Cancel a run; its source queries stop within seconds.

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

Status	Description	Body
204	No Content	—

RetryDiscoveryRun

POST /api/v1/workspaces/{workspaceId}/discovery-runs/{runId}:retry

Resume a failed or cancelled run from its first unfinished stage.

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

Status	Description	Body
202	Accepted	RunAccepted

Response 202: RunAccepted

Field	Type	Notes
jobId	uuid
runId	uuid

ListDriftEvents

GET /api/v1/workspaces/{workspaceId}/drift-events

Schema drift events of a workspace (or one source), newest first.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
sourceId	query	uuid	no
status	query	DriftStatus	no
breakingOnly	query	boolean	no
limit	query	int32	no

Status	Description	Body
200	OK	DriftEventDto[]

GetDriftEvent

GET /api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}

One schema drift event with its impact and the change request proposing the fix.

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

Status	Description	Body
200	OK	DriftEventDto

Response 200: DriftEventDto

Field	Type	Notes
acknowledgedAt	date-time?
acknowledgedBy	string?
affectedObjects	string[]
affectsRelease	boolean
after	string?
before	string?
breaking	boolean
changeRequestModelId	uuid?
changeRequestNumber	int32?
column	string?
dataSourceId	uuid
dataSourceName	string
detectedAt	date-time
evidence	string?
id	uuid
kind	DriftKind	One of TableAdded, TableRemoved, TableRenamed, ColumnAdded, ColumnRemoved, ColumnRenamed, ColumnTypeChanged, KeyChanged, ViewDefinitionChanged
newColumn	string?
newSchema	string?
newTable	string?
proposedFix	string?
resolutionNote	string?
resolvedAt	date-time?
resolvedBy	string?
runId	uuid
schema	string
status	DriftStatus	One of Open, Acknowledged, Resolved
summary	string
table	string

AcknowledgeDriftEvent

POST /api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}:acknowledge

Acknowledge a drift event (it stays listed until resolved).

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

Status	Description	Body
204	No Content	—

ResolveDriftEvent

POST /api/v1/workspaces/{workspaceId}/drift-events/{driftEventId}:resolve

Resolve a drift event (fix merged, source reverted or change accepted).

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

Request body (application/json): ResolveDriftEventRequest

Field	Type	Notes
note	string?	Why the drift is resolved (optional, at most 500 characters).

Status	Description	Body
204	No Content	—

GetTableDetail

GET /api/v1/workspaces/{workspaceId}/snapshots/{snapshotId}/tables/{tableId}

A table with columns, profiles, keys, indexes and declared relationships.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
snapshotId	path	uuid	yes
tableId	path	uuid	yes

Status	Description	Body
200	OK	TableDetailDto

Response 200: TableDetailDto

Field	Type	Notes
classification	TableClassificationDto?
columns	ColumnDto[]
comment	string?
foreignKeys	ForeignKeyDto[]
hash	string
id	uuid
indexes	IndexDto[]
kind	string
name	string
primaryKey	KeyDto?
profileNote	string?
profileStatus	string
referencedBy	ForeignKeyDto[]
rowCount	int64?
rowCountEstimate	int64?
rowCountExact	boolean
sampleSize	int64?
schema	string
snapshotId	uuid
uniqueKeys	KeyDto[]
viewDefinition	string?

GetSchemaTree

GET /api/v1/workspaces/{workspaceId}/snapshots/{snapshotId}/tree

Schemas and tables of a snapshot.

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

Status	Description	Body
200	OK	SchemaTreeDto

Response 200: SchemaTreeDto

Field	Type	Notes
dataSourceId	uuid
dataSourceName	string
schemas	TreeSchemaDto[]
snapshotId	uuid
takenAt	date-time

CheckDataSourceDrift

POST /api/v1/workspaces/{workspaceId}/sources/{sourceId}:check-drift

Start a metadata-only drift scan compared with the last snapshot (F16). Progress: /jobs/{jobId}/events.

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

Status	Description	Body
202	Accepted	RunAccepted

Response 202: RunAccepted

Field	Type	Notes
jobId	uuid
runId	uuid

ScanDataSource

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

Start a discovery run (harvest + profile). Progress: /jobs/{jobId}/events.

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

Status	Description	Body
202	Accepted	RunAccepted

Response 202: RunAccepted

Field	Type	Notes
jobId	uuid
runId	uuid

ListSnapshots

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

Schema snapshots of a source, newest first.

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

Status	Description	Body
200	OK	SnapshotDto[]