Data Models

All API responses are parsed into typed Pydantic models. Every model uses extra="allow" so that new fields from the API are preserved without breaking existing code.

Product Models

`Product`

Full product representation returned by detail endpoints.

Field	Type	Description
`id`	`UUID`	Product UUID
`name`	`str`	Display name
`slug`	`str`	URL-friendly identifier
`description_markdown`	`str \| None`	Markdown description
`product_type`	`str \| None`	Type (`table`, `view`, `dashboard`, etc.)
`tags`	`list[str]`	Tags
`is_archived`	`bool`	Whether the product is archived
`space_id`	`UUID \| None`	Owning space UUID
`quality_health`	`dict \| None`	Quality health summary
`created_at` / `updated_at`	`datetime \| None`	Timestamps

`ProductSummary`

Lightweight product used in list responses (subset of Product fields).

Refresh Models

`ProductRefreshResponse`

A recorded refresh event.

Field	Type	Description
`id`	`UUID`	Refresh UUID
`product_id`	`UUID`	Product UUID
`status`	`RefreshStatus`	Status enum (`success`, `failure`, `running`)
`trigger_source`	`TriggerSource`	Source enum (`manual`, `airflow`, `dbt`, etc.)
`started_at` / `completed_at`	`datetime \| None`	Timestamps
`row_count`	`int \| None`	Rows processed
`metadata`	`dict \| None`	Extra metadata

`ProductRefreshSummary`

Lightweight refresh used in list responses.

`ProductRefreshStats`

Aggregate statistics (total refreshes, success rate, average duration).

`ProductRefreshCreate`

Input model for creating a refresh event.

Enums: `RefreshStatus`, `TriggerSource`

String enums for type-safe status and trigger source values.

Quality Models

`QualityCheck`

Quality check definition.

Field	Type	Description
`id`	`UUID`	Check UUID
`name`	`str`	Check name
`slug`	`str`	URL-friendly slug
`check_type`	`str`	Type (`sql`, `row_count`, `manual`, etc.)
`query`	`str \| None`	SQL query
`status`	`str`	Current status
`product_ids`	`list[UUID]`	Linked product UUIDs

`CheckExecution`

A single execution result.

Field	Type	Description
`id`	`UUID`	Execution UUID
`check_id`	`UUID`	Parent check UUID
`status`	`str`	Result (`passed`, `failed`, `warning`, `error`)
`value`	`float \| None`	Measured value
`is_passed`	`bool`	Whether the check passed
`executed_at`	`datetime \| None`	Execution timestamp

`CheckStats`

Aggregated check statistics (pass rate, execution count, trends).

Connector Models

`Connector`

Field	Type	Description
`id`	`UUID`	Connector UUID
`name`	`str`	Display name
`connector_type`	`str`	Type (`postgresql`, `bigquery`, `dbt`, etc.)
`config`	`dict \| None`	Connection configuration

`SyncJob`

A metadata sync job triggered by connectors.sync() or upload_dbt_manifest().

Source System Models

`SourceSystem`

Inventory record for an external source system.

Field	Type	Description
`id`	`UUID`	Source system UUID
`space_id`	`UUID`	Owning space UUID
`name`	`str`	Display name
`platform_type`	`str`	Platform type, such as `snowflake`, `postgresql`, or `salesforce`
`description_markdown`	`str \| None`	Markdown description
`documentation_url` / `runbook_url`	`str \| None`	Documentation links
`business_purpose`	`str \| None`	Business purpose
`system_owner` / `system_owner_email`	`str \| None`	Owner details
`support_channel`	`str \| None`	Support channel
`contact_persons`	`list[dict[str, str]]`	Additional contacts
`role_count` / `connector_count`	`int`	Summary counts
`roles`	`list[SourceSystemRole]`	Nested roles when returned by detail endpoints
`connectors`	`list[ConnectorSummary]`	Linked connector summaries

`SourceSystemRole`

Role defined on a source system.

Field	Type	Description
`id`	`UUID`	Role UUID
`source_system_id`	`UUID`	Parent source system UUID
`name`	`str`	Role display name
`role_identifier`	`str \| None`	External role identifier
`access_level`	`str`	Access level
`workflow_id` / `workflow_definition_id`	`UUID \| None`	Linked workflow references

`SourceSystemCredential`

Masked credential attached to a source system. Secret values are never returned.

Field	Type	Description
`id`	`UUID`	Credential UUID
`source_system_id`	`UUID`	Parent source system UUID
`name`	`str`	Credential display name
`credential_type`	`str`	Credential type
`connection_config`	`dict`	Non-secret connection settings
`is_active`	`bool`	Whether the credential is active
`has_secret`	`bool`	Whether a secret is stored

`SourceSystemRoleDetail`

Detailed role response including users with access.

`ConnectorSummary`

Lightweight connector reference embedded in source system responses.

Space Models

`Space`

Field	Type	Description
`id`	`UUID`	Space UUID
`name`	`str`	Space name
`slug`	`str`	URL-friendly slug

`SpaceMember`

A user's membership in a space with their role.

Issue Models

`Ticket`

Full ticket representation.

Field	Type	Description
`id`	`UUID`	Ticket UUID
`title`	`str`	Ticket title
`description_markdown`	`str`	Markdown body
`priority`	`str`	Priority (`low`, `medium`, `high`, `critical`)
`status`	`str`	Status (`open`, `in_progress`, `resolved`, `closed`)
`reporter_id` / `assignee_id`	`UUID \| None`	User UUIDs
`space_id` / `space_slug`	`UUID \| None` / `str \| None`	Space context
`impact_assessment`	`ImpactAssessment \| None`	Impact details
`products_info`	`list[ProductLink]`	Linked products
`comments`	`list[TicketComment]`	Comments
`created_at` / `updated_at`	`datetime \| None`	Timestamps

`TicketComment`

A comment on a ticket.

`ImpactAssessment`

Impact assessment details (business impact, technical impact, reach, effort).

`ProductLink`

Lightweight product reference (id, name).

Alert Models

`UnifiedAlert`

Aggregated alert from the central feed. Contains fields from DQ, Smart, and Product alert sources.

Field	Type	Description
`id`	`str`	Alert identifier
`status`	`str`	`open` or `resolved`
`severity`	`str`	Severity level
`source`	`str`	Alert source type
`product_name` / `product_slug`	`str \| None`	Product context
`check_name` / `check_type`	`str \| None`	DQ check context
`annotations`	`list[dict] \| None`	Annotations

`ProductAlert`

Product banner alert.

Field	Type	Description
`id`	`UUID`	Alert UUID
`product_id`	`UUID`	Product UUID
`severity`	`str`	`info`, `warning`, or `critical`
`title`	`str`	Alert title
`message`	`str \| None`	Detailed message
`is_active`	`bool`	Whether the alert is active
`expires_at`	`datetime \| None`	Expiration timestamp

`AlertAnnotation`

An annotation on any alert type.

Field	Type	Description
`id`	`UUID`	Annotation UUID
`user_id`	`UUID`	Author UUID
`comment`	`str`	Annotation text
`created_at`	`datetime \| None`	Timestamp

Search Models

`SearchResult`

A unified search result with a type discriminator. Type-specific fields are only populated for results of the corresponding entity kind.

Field	Type	Description
`id`	`UUID`	Entity UUID
`name`	`str`	Display name
`description`	`str \| None`	Entity description
`type`	`str`	Entity kind (`product`, `issue`, `meeting`, `source_system`, `connector`, `user`, `comment`, `contract`)
`product_type`	`str \| None`	Product type (products only)
`provider`	`str \| None`	Provider name (products only)
`status`	`str \| None`	Status (meetings only)
`scheduled_at`	`str \| None`	Scheduled time (meetings only)
`platform_type`	`str \| None`	Platform type (source systems only)
`priority`	`str \| None`	Priority level (issues only)
`email`	`str \| None`	Email address (users only)
`product_id`	`UUID \| None`	Parent product UUID (comments only)
`product_name`	`str \| None`	Parent product name (comments only)

Product Models​

Product​

ProductSummary​

Refresh Models​

ProductRefreshResponse​

ProductRefreshSummary​

ProductRefreshStats​

ProductRefreshCreate​

Enums: RefreshStatus, TriggerSource​

Quality Models​

QualityCheck​

CheckExecution​

CheckStats​

Connector Models​

Connector​

SyncJob​

Source System Models​

SourceSystem​

SourceSystemRole​

SourceSystemCredential​

SourceSystemRoleDetail​

ConnectorSummary​

Space Models​

Space​

SpaceMember​

Issue Models​

Ticket​

TicketComment​

ImpactAssessment​

ProductLink​

Alert Models​

UnifiedAlert​

ProductAlert​

AlertAnnotation​

Search Models​

SearchResult​