Skip to main content
You’ll need an API key to follow this guide. Request one from your DriftGuard dashboard or your waitlist invite email.
All examples use the base URL: 
https://api.driftguard.dev/api/v1
All endpoints require the X-API-Key header. The only exception is GET /api/v1/health.

​
1. Set your API key

Your key must match the format dg_live_<24+ chars> or dg_test_<24+ chars>. 
    export DRIFTGUARD_KEY="dg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Use a dg_live_ key for production and a dg_test_ key for development and CI. You can create and manage keys from your dashboard. Keys are shown in full only once at creation — store yours immediately.

​
2. (Optional) Infer a contract from sample data

Not sure what your contract schema should look like? Send a sample JSON payload and DriftGuard will generate the column definitions for you automatically. 
curl -s -X POST https://api.driftguard.dev/api/v1/contracts/infer \
  -H "X-API-Key: $DRIFTGUARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sample": {
      "user_id": 1,
      "email": "user@example.com",
      "created_at": "2026-01-01T00:00:00Z"
    }
  }'
Sample response: 
{
  "columns": [
    { "name": "user_id",    "type": "integer",   "required": true },
    { "name": "email",      "type": "string",    "required": true },
    { "name": "created_at", "type": "timestamp", "required": true }
  ]
}
Copy these columns into your contract creation request in the next step.

​
3. Create your first contract

curl -s -X POST https://api.driftguard.dev/api/v1/contracts \
  -H "X-API-Key: $DRIFTGUARD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "users_production",
    "schema": {
      "columns": [
        { "name": "user_id",    "type": "integer",   "required": true },
        { "name": "email",      "type": "string",    "required": true },
        { "name": "created_at", "type": "timestamp", "required": true }
      ]
    }
  }'
Sample response: 
{
  "id": "your_contract_id_here",
  "name": "users_production",
  "version": 1,
  "created_at": "2026-03-01T18:00:00Z",
  "updated_at": "2026-03-01T18:00:00Z"
}
Save the id from the response — you’ll need it to run checks against this contract.
Valid column types: string, integer, number, boolean, date, timestamp, json. Any type outside this list will be rejected.

​
4. Run a schema check

Each check costs 1 credit and compares an incoming schema against your saved contract. 
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"  }
      ]
    }
  }'
Sample response: 
{
  "id": "your_check_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"
}
The three possible result values are:
ResultSeverity ScoreMeaning
pass0 – 19Schema matches contract
warning20 – 89Drift detected, may cause issues
breaking90 – 100Drift will break downstream consumers

​
5. Use the result in CI

Exit with a non-zero code on breaking changes to fail your pipeline or pull request check. 
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.

​
6. Check your usage

curl -s https://api.driftguard.dev/api/v1/usage \
  -H "X-API-Key: $DRIFTGUARD_KEY"

{
  "credits_remaining": 499,
  "credits_used": 1,
  "total_checks": 1
}
The rate limit is 100 requests per minute per API key. If you exceed it, you’ll receive a 429 Too Many Requests response.

​
Next Steps

Understand contracts

Learn how to model your datasets as contracts, including versioning and valid types.

Severity scoring

Understand exactly how the 0–100 severity score is calculated.

Webhooks

Get notified instantly when a breaking check is detected.

API Reference

Full endpoint reference with all parameters and response shapes.