Finds where your API drifted from its spec.

An open-source CLI and MCP server that runs your OpenAPI spec against a live implementation and tells you which side to fix.

npx apidrifter plan openapi.yaml
Turn the spec into a request plan with the slots an agent or you fill in.
npx apidrifter run openapi.yaml --base-url http://localhost:3000
Execute the plan against a running server and verify every response.
npx apidrifter serve
The same loop as an MCP server, so any agent can drive it.

How it works

01

Plan

The engine reads the spec and proposes one request per operation, with the parameters, body and auth it needs. Values come from the spec’s own examples; an agent or a small file supplies the rest.

02

Run

Requests go to your dev, staging or production server. Responses are matched to the operation and validated: status, media type, headers and body, with the schema’s direction taken into account.

03

Report

Every finding carries two fixes: what to change in the implementation if the spec is the truth, and what to change in the spec if the implementation is. Humans read it; agents act on it. The rules reference lists every finding the engine can report.

What is API drift?

API drift is the gap between what an API’s published OpenAPI document says and what the live implementation actually does: a field typed as an integer that arrives as a string, a required property that is sometimes missing, a null the schema forbids, a status code nobody documented. It breaks generated clients, typed SDKs, mocks and contract tests, because all of them trust the document. It appears whenever a spec is written by hand and maintained separately from the code, or generated once and edited afterwards.

  • Spec ahead of implementation. The document describes fields or responses the server does not produce yet, or never will.
  • Implementation ahead of spec. The server changed and the document was not updated, which is the most common form in our survey of public APIs.
  • Both drifting from an older version. Spec and server each moved in different directions from a shared ancestor, so neither is a reliable description of the other.

Also a spec differ

The same engine compares two versions of a spec and classifies every change as breaking, warning or info, knowing that a field becoming required is breaking in a request and harmless in a response. The design document explains this polarity model.

npx apidrifter breaking old.yaml new.yaml   # exit 1 on breaking changes, for CI
npx apidrifter mcp snapshot https://mcp.example.com/mcp --out before.json
npx apidrifter mcp diff before.json https://mcp.example.com/mcp

MCP servers are covered too: tools, resources and prompts are snapshotted and diffed, and a changed tool description is tracked as a change, because descriptions are what agents act on.

9 of 13 public APIs do not match their own spec.

We sent read-only requests to 13 public APIs that publish an OpenAPI document and found 171 hard violations on successful responses: wrong types, missing required fields, nulls the schema forbids. Every request is reproducible.

Read the survey · examples: Discourse (meta.discourse.org), GitHub REST API (unauthenticated)

Frequently asked questions

Does my API match its OpenAPI spec?
Run apidrifter run against your server with your spec. It sends one request per operation, compares every response to the documented status, media type, headers and schema, and reports each mismatch with a fix for the spec and a fix for the implementation. If it reports nothing, the operations it could exercise match.
How is this different from Schemathesis or contract testing?
Schemathesis fuzzes your API with generated data to find crashes and schema violations. API Drifter plans one realistic request per operation, lets a person or an agent supply real values and auth, and reports which side to fix. It also diffs spec versions and MCP servers, which fuzzers do not do.
How is this different from oasdiff or Bump.sh?
oasdiff and Bump.sh compare two versions of a spec. API Drifter does that too, with polarity-aware classification, and additionally compares a spec to the live implementation and covers MCP servers. It is open source under Apache-2.0 and runs locally.
Can an agent use it?
Yes. apidrifter serve exposes plan, run, verify, diff and the MCP snapshot tools as an MCP server over stdio, so a coding agent can check an API it just changed and act on the two-sided fixes without a person in the loop.
Does it send my spec anywhere?
No. The CLI runs on your machine and only talks to the server you point it at with --base-url. Specs, observations and reports stay local unless you choose to share them.
What does it cost?
Nothing. The CLI and engine are open source under Apache-2.0 and free to use. A hosted service for continuous monitoring and history is planned.

Install

npm install -g apidrifter    # or run it with npx, as above

Node 22.12 or newer. Apache-2.0. The CLI sends requests only where you point it; URLs other than localhost must be HTTPS. Secrets passed as headers are never written to output.

CLI reference · Rules reference· Design ·GitHub ·npm