Data contracts

Data contracts describe expected schema, quality rules, and service expectations (SLAs) for datasets or tables. The API lets you manage contract lifecycle (draft, active, deprecated), assign contracts to resources, validate incoming data, inspect violations, and resolve issues after remediation.

Authorization: Bearer YOUR_API_KEY_HERE

If your workspace uses URL versioning, insert /v1 before /api in the path. See API reference.

List contracts

GET https://api.planasonix.com/api/contracts

{
  "data": [
    {
      "id": "ctr_01j9k7p8q9r0s1t2",
      "name": "orders_fact_v2",
      "status": "active",
      "version": 2,
      "owner_team": "data-platform",
      "updated_at": "2025-03-26T09:00:00Z"
    }
  ],
  "meta": {
    "page": { "limit": 50, "cursor": null }
  }
}

Create contract

POST https://api.planasonix.com/api/contracts
Content-Type: application/json

A typical contract bundles schema expectations, quality checks, and SLA metadata.

{
  "name": "customer_360_core",
  "description": "Golden customer attributes for downstream CRM and analytics",
  "schema": {
    "primary_key": ["customer_id"],
    "columns": [
      { "name": "customer_id", "type": "string", "nullable": false },
      { "name": "email", "type": "string", "nullable": true },
      { "name": "lifetime_value_cents", "type": "integer", "nullable": false }
    ]
  },
  "quality": {
    "rules": [
      {
        "id": "email_format",
        "type": "regex",
        "column": "email",
        "pattern": "^[^@]+@[^@]+\\.[^@]+$"
      },
      {
        "id": "non_negative_ltv",
        "type": "sql_expression",
        "expression": "lifetime_value_cents >= 0"
      }
    ]
  },
  "sla": {
    "freshness_max_lag_minutes": 60,
    "completeness_threshold_pct": 99.5
  }
}

{
  "data": {
    "id": "ctr_01j9k8u9v0w1x2y3",
    "name": "customer_360_core",
    "status": "draft",
    "version": 1,
    "created_at": "2025-03-27T13:20:00Z"
  }
}

Get contract details

GET https://api.planasonix.com/api/contracts/{id}

Update contract

PUT https://api.planasonix.com/api/contracts/{id}
Content-Type: application/json

{
  "sla": {
    "freshness_max_lag_minutes": 30,
    "completeness_threshold_pct": 99.9
  }
}

Delete contract

DELETE https://api.planasonix.com/api/contracts/{id}

Deleting a contract may fail if it is still assigned to cataloged tables or active pipelines. Unassign or deprecate first when your policy requires retention of history.

Activate contract

POST https://api.planasonix.com/api/contracts/{id}/activate

{
  "data": {
    "id": "ctr_01j9k8u9v0w1x2y3",
    "status": "active",
    "activated_at": "2025-03-27T14:00:00Z"
  }
}

Deprecate contract

POST https://api.planasonix.com/api/contracts/{id}/deprecate
Content-Type: application/json

{
  "reason": "Replaced by customer_360_core_v2",
  "successor_contract_id": "ctr_01j9k9z0a1b2c3d4"
}

Validate data against contract

POST https://api.planasonix.com/api/contracts/{id}/validate
Content-Type: application/json

{
  "resource_type": "table",
  "resource_id": "cat_tbl_01inventory",
  "sample_limit": 10000
}

{
  "data": {
    "contract_id": "ctr_01j9k8u9v0w1x2y3",
    "passed": false,
    "checked_at": "2025-03-27T14:05:00Z",
    "summary": {
      "rows_evaluated": 10000,
      "violations": 42,
      "rules_failed": ["email_format", "non_negative_ltv"]
    }
  }
}

List violations

GET https://api.planasonix.com/api/contracts/{id}/violations

{
  "data": [
    {
      "id": "cvi_01j9ka1b2c3d4e5f6",
      "contract_id": "ctr_01j9k8u9v0w1x2y3",
      "rule_id": "email_format",
      "status": "open",
      "detected_at": "2025-03-27T03:15:00Z",
      "affected_rows_estimate": 18,
      "sample_values": ["not-an-email", "missing@"]
    }
  ]
}

List contract versions

GET https://api.planasonix.com/api/contracts/{id}/versions

{
  "data": [
    {
      "version": 2,
      "status": "active",
      "published_at": "2025-03-20T10:00:00Z",
      "changelog": "Tightened LTV rule; added email regex"
    },
    {
      "version": 1,
      "status": "deprecated",
      "published_at": "2025-01-05T10:00:00Z"
    }
  ]
}

List assigned resources

GET https://api.planasonix.com/api/contracts/{id}/assignments

{
  "data": [
    {
      "resource_type": "catalog_table",
      "resource_id": "cat_tbl_01inventory",
      "assigned_at": "2025-03-22T16:00:00Z",
      "assigned_by": "usr_01h8abc"
    }
  ]
}

Assign contract to resource

POST https://api.planasonix.com/api/contracts/{id}/assign
Content-Type: application/json

{
  "resource_type": "catalog_table",
  "resource_id": "cat_tbl_01inventory"
}

Unassign contract

POST https://api.planasonix.com/api/contracts/{id}/unassign
Content-Type: application/json

{
  "resource_type": "catalog_table",
  "resource_id": "cat_tbl_01inventory"
}

Resolve violation

POST https://api.planasonix.com/api/contract-violations/{id}/resolve
Content-Type: application/json

Use the violation id returned from the violations list (cvi_*).

{
  "resolution": "fixed_upstream",
  "notes": "Backfilled invalid emails from CRM export 2025-03-27",
  "resolved_by": "usr_01h8abc"
}

{
  "data": {
    "id": "cvi_01j9ka1b2c3d4e5f6",
    "status": "resolved",
    "resolved_at": "2025-03-27T15:30:00Z"
  }
}

Data contracts (guides)

Concepts and workflows in the product.

Data catalog API

Tables, lineage, and contract links.

Overview

Data platform

Orchestration

Integration

Governance

Iceberg Catalog

Platform

List contracts

Create contract

Get contract details

Update contract

Delete contract

Activate contract

Deprecate contract

Validate data against contract

List violations

List contract versions

List assigned resources

Assign contract to resource

Unassign contract

Resolve violation

Data contracts (guides)

Data catalog API

​List contracts

​Create contract

​Get contract details

​Update contract

​Delete contract

​Activate contract

​Deprecate contract

​Validate data against contract

​List violations

​List contract versions

​List assigned resources

​Assign contract to resource

​Unassign contract

​Resolve violation

​Related topics

Data contracts (guides)

Data catalog API

List contracts

Create contract

Get contract details

Update contract

Delete contract

Activate contract

Deprecate contract

Validate data against contract

List violations

List contract versions

List assigned resources

Assign contract to resource

Unassign contract

Resolve violation

Related topics