Run Check

Compare an incoming schema against a saved contract and get an instant verdict.

Endpoint

POST /api/v1/check
Host: api.driftguard.dev

Each call to this endpoint deducts 1 credit from your account. Check your balance anytime via GET /api/v1/usage.

---

Request

curl -s -X POST https://api.driftguard.dev/api/v1/check \
  -H "X-API-Key: $DRIFTGUARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "your_contract_id_here",
    "incoming_schema": {
      "columns": [
        { "name": "user_id",    "type": "integer" },
        { "name": "created_at", "type": "string"  }
      ]
    }
  }'

Request Body

Field	Type	Required	Description
contract_id	string	✅	ID of the contract to check against
incoming_schema.columns	array	✅	List of columns from the actual data source
incoming_schema.columns[].name	string	✅	Column name
incoming_schema.columns[].type	string	✅	Column type — must be one of string, integer, number, boolean, date, timestamp, json

---

Response

{
  "id": "your_check_id_here",
  "contract_id": "your_contract_id_here",
  "result": "breaking",
  "severity": 70,
  "diff": {
    "removed": ["email"],
    "type_changes": [
      { "column": "created_at", "from": "timestamp", "to": "string" }
    ],
    "added": []
  },
  "credits_used": 1,
  "created_at": "2026-03-01T18:00:14Z"
}

Response Fields

Field	Type	Description
id	string	Unique identifier for this check — use it with GET /api/v1/checks/ to retrieve later
contract_id	string	The contract this check was run against
result	string	pass, warning, or breaking
severity	integer	Score from 0–100. See Severity Levels
diff.removed	array	Column names present in the contract but missing from the incoming schema
diff.type_changes	array	Columns whose type changed, with from and to values
diff.added	array	Column names present in the incoming schema but not in the contract
credits_used	integer	Always 1
created_at	string	ISO 8601 timestamp of when the check was run

---

How Severity is Scored

The severity score is calculated from the diff and capped at 100:

Change Type	Points
Required column removed	+40
Optional column removed	+20
Column type changed	+30 per column
New column added	+5 per column

The score then maps to a result:

Result	Severity Range	Meaning
pass	0 – 19	Schema matches contract
warning	20 – 89	Drift detected, may cause issues
breaking	90 – 100	Drift will break downstream consumers

---

Error Responses

Status	Meaning
400	Invalid request body — bad column type or missing required field
401	Missing or invalid X-API-Key
403	Account has no credits remaining
404	Contract not found, or belongs to a different user
429	Rate limit exceeded — 100 req/min per key

---

Get Check

Retrieve a historical check result by ID.

Severity Levels

Understand how the 0–100 severity score is calculated in detail.