5 min read

Resolving live API drift

Drift means the deployed API no longer matches the declared spec. StateAnchor detects this in two ways: spec drift (the YAML file changed since the last sync) and runtime drift (the live API scanner observed behavior that differs from the canonical IR). This guide covers what to do when drift is detected.

What drift detection means

The scanner fetches the OpenAPI document from your running service and compares it against the IR built from stateanchor.yaml. When it finds a difference -- a field missing from a response, a type that changed, an endpoint that behaves differently -- it flags the project as drifted.

Drift is not an error. It is an operational signal. It means the spec and reality are out of sync, and someone needs to decide which one is correct.

How to find drift in the dashboard

1. Project list: The dashboard shows a yellow "Drift detected" indicator next to any project where the current file SHA differs from the last synced SHA.
2. Project detail: Click into the project. The status strip at the top shows the drift state. If drifted, you will see which fields or endpoints diverged in the latest sync run detail.
3. Sync run detail: Click a sync run in the history section. The gate findings show exactly which operations were detected -- endpoint added, field removed, type changed, etc.

Resolution path A: Update the spec

When to use: The API changed intentionally. A developer shipped a new field, deprecated an endpoint, or modified a response shape -- and the spec was not updated. The deployed API is correct; the spec is stale.

1. Edit stateanchor.yaml in your repo to match the current API behavior.
2. Commit and push. StateAnchor will run a new sync.
3. The gate evaluates the diff. If the changes are additive (INFO lane), the sync proceeds and artifacts regenerate.
4. The project returns to "In sync" once the sync completes.

This is the most common resolution. Most drift comes from spec staleness, not from deployment errors.

Resolution path B: Fix the deployed API

When to use: The API drifted unintentionally. A hotfix changed a response shape, a migration altered a column type, or a feature flag modified behavior in production. The spec is correct; the deployed API needs to be reverted or fixed.

1. Identify the root cause from the drift findings (which field, which endpoint).
2. Deploy a fix to the API that restores the expected behavior.
3. Run a manual sync or wait for the next push. The scanner will confirm the API matches the spec again.

Resolution path C: Temporary exception

When to use: The team needs time to align. The drift is known, the fix is in progress, but you do not want the gate to block other changes in the meantime.

1. In project settings, create a drift exception for the specific endpoint and change kind.
2. Provide a named approver and set an expiration (maximum 90 days).
3. The excepted finding is suppressed from gate evaluation until the exception expires.
4. When the underlying issue is fixed, the exception can be deleted early or left to expire.

Exceptions are scoped. They suppress one specific finding, not the entire gate. If a new breaking change is pushed alongside an excepted one, the gate still blocks.

How to verify drift is resolved

After applying your fix (spec update, API fix, or exception), trigger a new sync -- either by pushing a commit or clicking the Sync button on the project detail page. When the sync completes:

• The project status changes from "Drift detected" to "In sync".
• The latest sync run shows gate action: proceed.
• The drift indicator on the dashboard disappears.

Common causes of drift