Skip to main content
A check is a single evaluation of an incoming schema against a stored contract. You run a check by POSTing to POST /api/v1/check. DriftGuard compares the incoming columns against the contract and returns an instant verdict. One check = one credit.

​
What You Send

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"  },
        { "name": "new_field",  "type": "integer" }
      ]
    }
  }'
FieldRequiredDescription
contract_id✅The ID of the contract to check against
incoming_schema.columns✅Array of column objects from your actual data source
incoming_schema.columns[].name✅Column name (case-sensitive)
incoming_schema.columns[].type✅One of string, integer, number, boolean, date, timestamp, json

​
What You Get Back

{
  "id": "your_check_id_here",
  "contract_id": "your_contract_id_here",
  "result": "breaking",
  "severity": 75,
  "diff": {
    "removed": ["email"],
    "type_changes": [
      { "column": "created_at", "from": "timestamp", "to": "string" }
    ],
    "added": ["new_field"]
  },
  "credits_used": 1,
  "created_at": "2026-03-01T18:00:14Z"
}
FieldTypeDescription
idstringUnique check ID — use with GET /api/v1/checks/ to retrieve later
contract_idstringThe contract this check was run against
resultstringpass, warning, or breaking — see below
severityintegerScore from 0–100 — see Severity Levels
diff.removedarrayColumn names present in the contract but missing from incoming schema
diff.type_changesarrayColumns whose type changed, with from and to values
diff.addedarrayColumn names present in incoming schema but not in the contract
credits_usedintegerAlways 1
created_atstringISO 8601 timestamp of when the check was run

​
The result Field

The top-level result is always one of three values:
ResultSeverity RangeMeaning
pass0 – 19Incoming schema matches the contract. Safe to proceed.
warning20 – 89Drift detected — may cause issues. Review recommended.
breaking90 – 100Drift will break downstream consumers. Block this.
The result is derived from the severity score, not computed separately. If your score lands at 90 or above, the result is always breaking.

​
How the Severity Score is Calculated

Every difference found between the incoming schema and the contract contributes points to the severity score. The score is capped at 100.
Change TypePoints
Required column removed+40
Optional column removed+20
Column type changed+30 per column
New column added+5 per column
Example: A check where 1 required column is removed and 1 type change is found scores 40 + 30 = 70 → warning.

​
Change Types Explained

ChangeWhat it means
RemovedA column defined in the contract is missing from the incoming schema entirely
Type changedA column exists in both but its type differs (e.g. timestamp → string)
AddedA column exists in the incoming schema but was not defined in the contract

​
Using result in CI

The result field is machine-readable and designed for use in CI pipelines: 
RESULT=$(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": "email",   "type": "string"  }
      ]
    }
  }' | jq -r '.result')

echo "DriftGuard result: $RESULT"
[ "$RESULT" != "breaking" ] || exit 1
You can also fail on warning by changing the condition to [ "$RESULT" = "pass" ] || exit 1 for stricter pipelines.

​
Check History

Every check result is stored and retrievable by ID. Use GET /api/v1/checks/ to fetch a past check.

Severity Levels

Understand exactly how the 0–100 score maps to pass, warning, and breaking.

Run a Check

Full API reference for POST /api/v1/check.