API Usage

December 20, 2025 · View on GitHub

DriftHound provides a RESTful API for submitting Terraform drift check results.

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

See API Token Management for details on generating tokens.

Endpoints

Submit a Drift Check

Submit the results of a Terraform drift check for a specific project and environment.

Endpoint: POST /api/v1/projects/:project_key/environments/:environment_key/checks

Example Request:

curl -X POST \
  http://localhost:3000/api/v1/projects/my-project/environments/my-env/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "drift",
    "add_count": 2,
    "change_count": 1,
    "destroy_count": 0,
    "duration": 8.2,
    "raw_output": "Plan: 2 to add, 1 to change, 0 to destroy.",
    "directory": "infra/terraform/production",
    "repository": "https://github.com/myorg/infrastructure",
    "branch": "master"
  }'

Request Parameters

URL Parameters

Parameter	Type	Required	Description
`project_key`	string	Yes	Unique identifier for the project (alphanumeric, dashes, underscores)
`environment_key`	string	Yes	Unique identifier for the environment (alphanumeric, dashes, underscores)

Body Parameters

Parameter	Type	Required	Description
`status`	string	Yes	One of: `ok`, `drift`, `error`, `unknown`
`add_count`	integer	No	Number of resources to add
`change_count`	integer	No	Number of resources to change
`destroy_count`	integer	No	Number of resources to destroy
`duration`	float	No	Execution duration in seconds
`raw_output`	text	No	Full Terraform plan output
`directory`	string	No	Directory where Terraform is executed. Only set on first call; subsequent calls won't overwrite. Update via GUI.
`repository`	string	No	Repository URL (e.g., `https://github.com/org/repo`). Only set on first call; subsequent calls won't overwrite. Update via GUI.
`branch`	string	No	Repository branch (default: `main`). Only set on first call if different from default; update via GUI.
`notification_channel`	object	No	Optional notification channel configuration (see Advanced Features)

Response

Success Response (201 Created):

{
  "id": 123,
  "project_key": "my-project",
  "environment_key": "my-env",
  "status": "drift",
  "created_at": "2025-11-27T10:30:00Z"
}

Error Responses:

401 Unauthorized - Missing or invalid API token
422 Unprocessable Entity - Invalid status value or validation error

Status Values

Status	Description
`ok`	No drift detected - infrastructure matches state
`drift`	Drift detected - changes pending
`error`	Error running drift check
`unknown`	Initial state or unable to determine

Advanced Features

Notification Channel Configuration

You can optionally configure Slack notification channels per environment via the API:

curl -X POST \
  http://localhost:3000/api/v1/projects/my-project/environments/production/checks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "drift",
    "add_count": 2,
    "change_count": 1,
    "destroy_count": 0,
    "notification_channel": {
      "channel_type": "slack",
      "enabled": true,
      "config": {
        "channel": "#custom-alerts"
      }
    }
  }'

Notification Channel Parameters:

Parameter	Type	Required	Description
`channel_type`	string	Yes	Currently only `"slack"` is supported
`enabled`	boolean	No	Enable or disable notifications for this environment
`config.channel`	string	No	Slack channel name (e.g., `"#alerts"`). Falls back to global default if not provided

Notes:

The Slack token is always taken from the global configuration (SLACK_BOT_TOKEN or config/notifications.yml)
This allows you to override the notification channel per environment without exposing tokens in API requests
See Slack Notifications documentation for more details on notification setup

API Token Management

DriftHound provides a web-based interface for managing API tokens. Only admin users can create and manage tokens.

Using the Web UI (Recommended)

Log in as an admin user
Click API Tokens in the navigation bar
Enter a name for your token (e.g., "CI/CD Pipeline") and click Create Token
Important: Copy the token immediately - it will only be shown once!

The API Tokens page also displays:

A list of all existing tokens with partial token previews
Creation dates for each token
Delete buttons to revoke tokens
Usage examples showing how to authenticate API requests

Token Security

Tokens are only displayed once at creation time
Store tokens securely (e.g., in CI/CD secrets, environment variables)
Use descriptive names to identify token purposes
Revoke tokens that are no longer needed

Health Check Endpoint

DriftHound provides a health check endpoint for load balancers and monitoring systems:

Endpoint: GET /up

Response:

200 OK - Application is healthy
500 Internal Server Error - Application failed to boot

Note: Health check requests are not logged in production to prevent log clutter.

Best Practices

Use descriptive project and environment keys - Use kebab-case names like infrastructure-prod rather than cryptic codes
Always include raw_output - Helps with debugging and provides detailed context in the dashboard
Set appropriate durations - Helps track performance over time
Use environment variables for tokens - Never hardcode tokens in scripts
Configure notifications per environment - Use different Slack channels for production vs. staging alerts

Example Integration

GitHub Actions

- name: Check Terraform Drift
  run: |
    drifthound --tool=terraform \
      --project=my-infrastructure \
      --environment=production \
      --token=${{ secrets.DRIFTHOUND_TOKEN }} \
      --api-url=${{ secrets.DRIFTHOUND_URL }} \
      --dir=./terraform

GitLab CI

drift_check:
  script:
    - drifthound --tool=terraform
        --project=my-infrastructure
        --environment=production
        --token=$DRIFTHOUND_TOKEN
        --api-url=$DRIFTHOUND_URL
        --dir=./terraform