Skip to content

quickstart.mdx

Latest commit

 

History

History
221 lines (186 loc) · 5.57 KB

quickstart.mdx

File metadata and controls

221 lines (186 loc) · 5.57 KB
title Quickstart
description Run your first schema check in under 5 minutes.
You'll need an API key to follow this guide. Request one from your [DriftGuard dashboard](https://driftguard.dev/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>.

```bash export DRIFTGUARD_KEY="dg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` ```powershell $env: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](https://driftguard.dev/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:

Result Severity Score Meaning
pass 0 – 19 Schema matches contract
warning 20 – 89 Drift detected, may cause issues
breaking 90 – 100 Drift 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

Learn how to model your datasets as contracts, including versioning and valid types. Understand exactly how the 0–100 severity score is calculated. Get notified instantly when a breaking check is detected. Full endpoint reference with all parameters and response shapes.