Quality API

Manage quality checks, execute validations, and monitor data health across products.

Endpoints Overview

Method	Endpoint	Description
POST	/quality/checks	Create check
GET	/quality/checks	List quality checks
GET	/quality/checks/stats	Aggregated check stats
GET	/quality/checks/{id}	Get check details
GET	/quality/checks/{id}/stats	Single check stats
PATCH	/quality/checks/{id}	Update check
POST	/quality/checks/{id}/run	Trigger execution
GET	/quality/checks/{id}/executions	Execution history
POST	/quality/checks/{id}/archive	Toggle archive status
PATCH	/quality/executions/{id}/ignore	Toggle execution ignored flag

Slug-Based Endpoints

Method	Endpoint	Description
GET	/s/{space}/quality/{slug}	Get check by slug
GET	/s/{space}/quality/{slug}/executions	Execution history by slug
POST	/s/{space}/quality/{slug}/run	Trigger execution by slug
POST	/s/{space}/quality/{slug}/push	Push external result
GET	/s/{space}/quality/products/{slug}	Checks for a product

Change Governance Endpoints

Method	Endpoint	Description
POST	/quality/checks/{id}/propose	Propose a configuration change
POST	/quality/changes/{id}/approve	Approve a proposal
POST	/quality/changes/{id}/reject	Reject a proposal

Analytics Endpoints

Method	Endpoint	Description
GET	/quality/trends/{product_id}	Product quality trend
GET	/quality/executions	Space-wide executions
GET	/quality/trend	Space-wide daily trend
GET	/quality/execution-stats	Space execution stats

---

Check Types

Type	Description
sql_metric	Returns a numeric value from a SQL query
sql_condition	Asserts a SQL condition (e.g. count of bad rows = 0)
field_checks	Multiple field-level validations in a single check
reconciliation	Compare values between source and target queries
anomaly	Smart alerts based on historical baselines
custom	External metric pushed via API
manual	Manually inputted metric via UI
null_check	Verify null/not-null constraints
uniqueness	Check for duplicate values
type_check	Validate data types
range_check	Numeric/date range validation
pattern_check	Regex pattern matching
enum_check	Validate against allowed values
length_check	String length validation
freshness_check	Date/timestamp freshness

---

Create Quality Check

POST /quality/checks

Request Body

{
  "name": "No Future Dates",
  "slug": "no-future-dates",
  "check_type": "sql_metric",
  "description": "Ensure no orders have a future date",
  "product_ids": ["product-uuid-1", "product-uuid-2"],
  "field_id": "field-uuid",
  "connector_id": "connector-uuid",
  "configuration": {
    "sql_query": "SELECT COUNT(*) FROM orders WHERE order_date > {{cutoff_date}}",
    "expected_value": 0,
    "comparison": "equals"
  },
  "threshold_config": {
    "warn": 5,
    "crit": 10
  },
  "schedule_cron": "0 8 * * *",
  "parameters": [
    {
      "name": "cutoff_date",
      "type": "date",
      "default": "CURRENT_DATE",
      "description": "Upper bound date for validation",
      "required": false
    }
  ]
}

Key Fields

Field	Type	Description
name	string	Required. Descriptive identifier
slug	string	URL-friendly identifier, unique per space
check_type	string	Required. One of the check types above
product_ids	UUID[]	Associate with multiple data products
product_id	UUID	(Deprecated) Single product backward compat
field_id	UUID	Specific field within a product
connector_id	UUID	Data connector for SQL execution
configuration	object	Check-type-specific configuration
threshold_config	object	Warning/critical thresholds
schedule_cron	string	Cron expression for scheduling
parameters	object[]	Query parameter definitions

Parameter Definition

Field	Type	Default	Description
name	string	—	Required. Parameter name matching {{name}} in SQL
type	string	"string"	string, number, date, boolean
default	string	null	Default value if not overridden at runtime
description	string	null	Human-readable description
required	boolean	false	Whether a value must be supplied at execution

---

List Quality Checks

GET /quality/checks

Query Parameters

Parameter	Type	Description
space_id	uuid	Filter by space
include_archived	boolean	Include deprecated checks (default: false)

Response

{
  "items": [
    {
      "id": "...",
      "name": "No Future Dates",
      "slug": "no-future-dates",
      "check_type": "sql_metric",
      "product_ids": ["uuid-1", "uuid-2"],
      "product_names": ["Orders", "Sales"],
      "parameters": [
        { "name": "cutoff_date", "type": "date", "default": "CURRENT_DATE" }
      ],
      "latest_status": "pass",
      "latest_value": 0.0,
      "last_executed_at": "2026-01-15T10:30:00Z",
      "is_archived": false
    }
  ]
}

---

Trigger Check Execution

POST /quality/checks/{id}/run

Manually triggers a check outside its schedule. Supply optional runtime parameter overrides in the request body.

Request Body (optional)

{
  "parameters": {
    "cutoff_date": "2026-01-01"
  }
}

For manual check types, pass a value directly:

{
  "manual_value": 42.5
}

Response

{
  "id": "execution-uuid",
  "check_id": "check-uuid",
  "status": "pass",
  "actual_value": 0.0,
  "executed_at": "2026-01-15T10:30:00Z",
  "execution_message": "0 rows with future dates",
  "execution_details": { ... },
  "batch_id": null,
  "field_name": null,
  "field_check_type": null,
  "is_ignored": false
}

Execution Response Fields

Field	Type	Description
id	UUID	Execution identifier
check_id	UUID	Parent check
status	string	pass, warning, fail, error
actual_value	float	Measured metric
executed_at	datetime	When the check ran
execution_message	string	Human-readable result
execution_details	object	Detailed per-field results (field checks)
batch_id	UUID	Groups field-check sub-executions
field_name	string	Column name (field checks only)
field_check_type	string	Sub-check type (field checks only)
is_ignored	boolean	Excluded from statistics

---

Get Execution History

GET /quality/checks/{id}/executions

Query Parameters

Parameter	Type	Description
page	integer	Page number
size	integer	Items per page

Response

Paginated list of CheckExecutionResponse objects (see fields above). Total count is returned via X-Total-Count header.

---

Toggle Execution Ignored

PATCH /quality/executions/{id}/ignore

Mark an execution as ignored so it is excluded from statistics.

{
  "is_ignored": true
}

---

Toggle Archive

POST /quality/checks/{id}/archive

Toggles the is_deprecated flag. Archived checks are hidden from default listings.

---

Slug-Based API

These endpoints use human-readable slugs instead of UUIDs, designed for external system integration (CI/CD, dbt, Airflow).

Get Check by Slug

GET /s/{space_slug}/quality/{check_slug}

Trigger by Slug

POST /s/{space_slug}/quality/{check_slug}/run

Same body format as the UUID-based trigger endpoint.

Push External Result

POST /s/{space_slug}/quality/{check_slug}/push

{
  "status": "pass",
  "actual_value": 0.0,
  "execution_message": "Pipeline validation passed",
  "parameters": {
    "cutoff_date": "2026-01-15"
  }
}

Get Product Checks by Slug

GET /s/{space_slug}/quality/products/{product_slug}

Returns all quality checks associated with the given product.

---

Change Governance

For critical checks, modifications can be routed through an approval workflow.

Propose a Change

POST /quality/checks/{id}/propose

{
  "proposed_configuration": { "sql_query": "SELECT ..." },
  "proposed_name": "Updated Check Name",
  "proposed_description": "New description",
  "is_deprecation_request": false
}

Approve a Proposal

POST /quality/changes/{id}/approve

Reject a Proposal

POST /quality/changes/{id}/reject

Change Response

{
  "id": "...",
  "check_id": "...",
  "requested_by_id": "...",
  "approved_by_id": null,
  "proposed_configuration": { ... },
  "proposed_name": "Updated Name",
  "status": "pending",
  "created_at": "2026-01-15T10:00:00Z",
  "decided_at": null,
  "is_deprecation_request": false
}

---

Analytics

Product Quality Trend

GET /quality/trends/{product_id}

Returns daily pass/fail aggregation for a specific product.

{
  "product_id": "...",
  "trends": [
    { "date": "2026-01-15", "pass_count": 10, "fail_count": 2, "avg_value": 0.5 },
    { "date": "2026-01-14", "pass_count": 12, "fail_count": 0, "avg_value": 0.0 }
  ]
}

Space Quality Trend

GET /quality/trend?days=30

Space Execution Stats

GET /quality/execution-stats

Parameter	Type	Description
time_filter	string	Time window filter
status_filter	string	Filter by status
search	string	Search checks by name

---

Alerts

List Alerts

GET /alerts

Query Parameters

Parameter	Type	Description
space_id	uuid	Filter by space
status	string	open, resolved
severity	string	critical, high, medium, low

Response

{
  "items": [
    {
      "id": "...",
      "execution_id": "...",
      "status": "open",
      "severity": "high",
      "description": "Data is stale (26 hours old)",
      "created_at": "2026-01-15T09:30:00Z",
      "resolved_at": null
    }
  ]
}

Acknowledge / Resolve Alert

PATCH /alerts/{id}

{
  "status": "resolved",
  "notes": "Pipeline backfill completed"
}