DriftSignal Documentation

Getting started

DriftSignal watches your APIs against their OpenAPI specs and tells you the moment a live response stops matching what the spec promises. There's nothing to install in your stack — you point DriftSignal at a spec, and it polls the live API on a schedule. DriftSignal currently polls GET (read) endpoints only; write-method endpoints (POST, PUT, DELETE) aren't polled yet — write-method monitoring and active contract testing are on the roadmap.

When you sign in, the Overview page summarizes the health of everything you monitor: how many watches are active, how many breaking and drift violations are currently open, how many watches are clean, and a list of your most recent violations. Use the left-hand navigation to move between Overview, Watches, Violations, Library, and Settings.

To start monitoring an API, head to Watches and create your first watch.

Creating a watch

A watch ties together an OpenAPI spec and the live API it describes. On the Watches page, click Add watch and fill in the form:

• Watch name — a label for this API (e.g. "Stripe API").
• OpenAPI spec URL — the public URL of your OpenAPI 3.x or Swagger 2.0 file.
• Base URL (optional) — where the live API runs, if it differs from the spec's declared server.
• Authentication (optional) — how DriftSignal authenticates when polling the API.

Authentication options

Pick the method your API requires from the Authentication dropdown:

• None — for public APIs that need no auth.
• Bearer token — paste a bearer token (e.g. sk_live_…); sent as an Authorization: Bearer header.
• API key header — provide a header name (e.g. X-API-Key) and its value.
• Basic auth — provide a username and password.

Click Create watch to save it. DriftSignal parses the spec, builds a map of endpoints, and begins polling on your plan's schedule. Only GET (read) endpoints in the spec are polled; write-method endpoints are skipped for now.

The watches list

Each watch in the list shows its name, spec URL, current violation count, and the time of its last run. Use Run to trigger an immediate check rather than waiting for the next scheduled poll, or the trash icon to delete the watch.

Third-party library

You can monitor APIs you don't control. The Library page is a catalog of common providers — Stripe, Twilio, GitHub, Shopify Admin, Slack, and PagerDuty — each pre-configured with its OpenAPI spec.

Browse by category (Payments, Communications, Developer Tools, E-commerce, Fintech, Operations, CRM) or view all providers at once. Each card describes what the provider's API covers; click Add watch to start monitoring it in one step — no need to track down the spec URL yourself.

This is how you find out the moment a provider changes their API, before the change breaks your integration. (Watches you add from the Library count toward your plan's watch limit, the same as any other watch.)

Reading violations

When a live response diverges from the spec, DriftSignal records a violation. Every violation has a severity:

• BREAKING  the response will break consumers — a missing required field, a wrong type, an undocumented status code.
• DRIFT  the response changed in a way that signals risk but isn't immediately breaking — an undocumented field, a format mismatch.

Grouped problems

A real-world API can produce hundreds of raw violations that are really just a handful of underlying problems — for example, the same undocumented field appearing on every endpoint. The Violations page groups these automatically, so you see distinct problems rather than raw noise.

Each row is one logical problem: its severity, a plain-language description (for example, "Undocumented field $.status_code" or "Status 404 undocumented"), and how many endpoints it affects. The page header shows the count of distinct problems alongside the total raw occurrences — so you can see at a glance that, say, 543 raw occurrences are really just 13 distinct problems.

Drilling into endpoints

Click any problem row to expand it and see every endpoint affected. This lets you confirm the scope of an issue — whether it's one endpoint or spread across your whole API — without leaving the page.

Silencing

Some violations are known and accepted — a third-party API that returns an undocumented field you've decided to live with. Use Silence on a problem to mute the entire group. Silenced problems:

• stop triggering alerts,
• are visually muted in the list,
• and, by default, no longer fail your CI/CD pipeline (see the drift gate).

A silenced problem stays silenced through recurrences and only clears when the underlying issue genuinely resolves. Use Unsilence to bring it back.

Filtering

Narrow the view with three filters:

• Watch — focus on a single API, or view all watches at once.
• Severity — show all problems, only breaking, or only drift.
• Date range — limit to problems seen within a window.

Exporting to CSV

The Export CSV button downloads a full, detailed list of violations — every endpoint, code, message, and timestamp — honoring whatever filters you currently have applied. Use it for reporting, sharing with your team, or analysis in a spreadsheet.

Alerts

DriftSignal notifies your team when new breaking drift appears, so you hear about it before your customers do. Manage notifications under Settings → Alert channels.

Every account has an email channel by default, sent to your account email. Click Add channel, choose a type, fill in its details, and click Save channel. Remove a channel with the trash icon next to it. DriftSignal supports four channel types:

Email

Send alerts to any address. Choose Email and enter the destination address — useful for routing to a shared team inbox or a distribution list. Available on every plan.

Slack

Post alerts into a Slack channel. You'll need an incoming webhook URL from Slack:

1. In Slack, go to api.slack.com/messaging/webhooks and create (or open) a Slack app for your workspace.
2. Enable Incoming Webhooks, then Add New Webhook to Workspace and pick the channel alerts should post to.
3. Copy the generated webhook URL (it looks like https://hooks.slack.com/services/…).
4. In DriftSignal, choose Slack, paste the URL into Slack webhook URL, and save.

Available on Team and Pro plans.

Webhook

POST alerts to your own HTTPS endpoint to wire DriftSignal into any system. Choose Webhook and enter your endpoint URL. When new breaking or drift violations appear, DriftSignal sends a POST with this JSON body:

{
  "source": "driftsignal",
  "spec_url": "https://api.example.com/openapi.json",
  "watch_id": "1c9848ec-…",
  "breaking_count": 1,
  "drift_count": 2,
  "violations": [
    {
      "severity": "breaking",
      "code": "MISSING_REQUIRED_FIELD",
      "endpoint": "GET /v1/customers",
      "message": "field 'id' missing from response"
    }
  ]
}

The violations array contains the new violations from this run (capped at 50). Your endpoint must be a public HTTPS URL — for security, DriftSignal will not post to internal or private addresses. Available on Team and Pro plans.

PagerDuty

Trigger PagerDuty incidents so on-call gets paged. You'll need an Events API V2 integration key (also called a routing key):

1. In PagerDuty, go to Services → Service Directory and open (or create) the service that should receive alerts.
2. On the service's Integrations tab, add an Events API V2 integration.
3. Copy the Integration Key — a 32-character string.
4. In DriftSignal, choose PagerDuty, paste it into PagerDuty routing key, and save.

Breaking violations trigger critical incidents; drift-only batches trigger warning. Available on the Pro plan.

Your plan determines which channels and features are available. You can see and change your plan under Settings → Plan:

CI/CD drift gate

Gate your deploy pipeline on API drift. The drift gate triggers a fresh check of a watch, waits for it to finish, and fails the build if breaking drift is found — so a breaking change is caught before it ships.

Setup

Three steps:

1. Create a watch for the API you want to gate on, and copy its watch ID.
2. Add your API token as a CI secret named DRIFTSIGNAL_TOKEN.
3. Add a step to your pipeline that runs the check.

GitHub Actions

- name: Check API for breaking drift
  env:
    DRIFTSIGNAL_TOKEN: ${{ secrets.DRIFTSIGNAL_TOKEN }}
  run: |
    curl -fsSL https://www.driftsignal.io/ci/driftsignal-check.sh -o driftsignal-check.sh
    chmod +x driftsignal-check.sh
    ./driftsignal-check.sh <WATCH_ID>

GitLab CI

drift-check:
  script:
    - curl -fsSL https://www.driftsignal.io/ci/driftsignal-check.sh -o driftsignal-check.sh
    - chmod +x driftsignal-check.sh
    - ./driftsignal-check.sh <WATCH_ID>

Any shell

DRIFTSIGNAL_TOKEN=ds_live_xxx ./driftsignal-check.sh <WATCH_ID>

Options

Configure the gate with environment variables:

Exit codes

Example output

A clean API — the check passes and the build continues:

DriftSignal: triggering check for watch 1c9848ec-…
DriftSignal: run a1b2c3 started; waiting for completion (timeout 120s)…
DriftSignal: 0 breaking, 2 drift (silenced excluded).
DriftSignal: no breaking drift. ✓
# exit code 0 — build passes

Breaking drift found — the check fails the build:

DriftSignal: triggering check for watch 1c9848ec-…
DriftSignal: run d4e5f6 started; waiting for completion (timeout 120s)…
DriftSignal: 3 breaking, 2 drift (silenced excluded).
::error:: 3 breaking drift violation(s) detected. Failing the build.
# exit code 1 — build fails