> ## Documentation Index
> Fetch the complete documentation index at: https://docs.planasonix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data contracts

> Define and enforce data quality 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.

```http theme={null}
Authorization: Bearer YOUR_API_KEY_HERE
```

<Info>
  If your workspace uses URL versioning, insert `/v1` before `/api` in the path. See [API reference](/api-reference/introduction).
</Info>

## List contracts

```http theme={null}
GET https://api.planasonix.com/api/contracts
```

```json theme={null}
{
  "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

```http theme={null}
POST https://api.planasonix.com/api/contracts
Content-Type: application/json
```

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

```json theme={null}
{
  "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
  }
}
```

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

## Get contract details

```http theme={null}
GET https://api.planasonix.com/api/contracts/{id}
```

## Update contract

```http theme={null}
PUT https://api.planasonix.com/api/contracts/{id}
Content-Type: application/json
```

```json theme={null}
{
  "sla": {
    "freshness_max_lag_minutes": 30,
    "completeness_threshold_pct": 99.9
  }
}
```

## Delete contract

```http theme={null}
DELETE https://api.planasonix.com/api/contracts/{id}
```

<Warning>
  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.
</Warning>

## Activate contract

```http theme={null}
POST https://api.planasonix.com/api/contracts/{id}/activate
```

```json theme={null}
{
  "data": {
    "id": "ctr_01j9k8u9v0w1x2y3",
    "status": "active",
    "activated_at": "2025-03-27T14:00:00Z"
  }
}
```

## Deprecate contract

```http theme={null}
POST https://api.planasonix.com/api/contracts/{id}/deprecate
Content-Type: application/json
```

```json theme={null}
{
  "reason": "Replaced by customer_360_core_v2",
  "successor_contract_id": "ctr_01j9k9z0a1b2c3d4"
}
```

## Validate data against contract

```http theme={null}
POST https://api.planasonix.com/api/contracts/{id}/validate
Content-Type: application/json
```

```json theme={null}
{
  "resource_type": "table",
  "resource_id": "cat_tbl_01inventory",
  "sample_limit": 10000
}
```

```json theme={null}
{
  "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

```http theme={null}
GET https://api.planasonix.com/api/contracts/{id}/violations
```

```json theme={null}
{
  "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

```http theme={null}
GET https://api.planasonix.com/api/contracts/{id}/versions
```

```json theme={null}
{
  "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

```http theme={null}
GET https://api.planasonix.com/api/contracts/{id}/assignments
```

```json theme={null}
{
  "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

```http theme={null}
POST https://api.planasonix.com/api/contracts/{id}/assign
Content-Type: application/json
```

```json theme={null}
{
  "resource_type": "catalog_table",
  "resource_id": "cat_tbl_01inventory"
}
```

## Unassign contract

```http theme={null}
POST https://api.planasonix.com/api/contracts/{id}/unassign
Content-Type: application/json
```

```json theme={null}
{
  "resource_type": "catalog_table",
  "resource_id": "cat_tbl_01inventory"
}
```

## Resolve violation

```http theme={null}
POST https://api.planasonix.com/api/contract-violations/{id}/resolve
Content-Type: application/json
```

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

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

```json theme={null}
{
  "data": {
    "id": "cvi_01j9ka1b2c3d4e5f6",
    "status": "resolved",
    "resolved_at": "2025-03-27T15:30:00Z"
  }
}
```

## Related topics

<CardGroup cols={2}>
  <Card title="Data contracts (guides)" icon="file-check" href="/governance/data-contracts">
    Concepts and workflows in the product.
  </Card>

  <Card title="Data catalog API" icon="database" href="/api-reference/catalog">
    Tables, lineage, and contract links.
  </Card>
</CardGroup>