- Home
- Skills
- APIs & Backend
- API Contract Drift Detection
API Contract Drift Detection
Detect breaking changes, semantic drift, and implementation mismatches in OpenAPI, GraphQL, and JSON schemas.
$5.99
Works with the AI Agents you already use
API Contract Drift Detection
Example session with this skill installed
Compare these two versions of the User API. The baseline has 'id' as a string, but the new one uses an integer. Is this breaking?
- Read your context and instructions
- Compiled the api contract drift
I have analyzed the two versions of the User API contract. The change in the id field type constitutes a high-severity breaking change for existing consumers.
API Drift Audit Report
| Finding ID | Severity | Classification | Confidence | Location | Element |
|---|---|---|---|---|---|
| DRIFT-001 | HIGH | BREAKING_CHANGE | HIGH | GET /users/{id} | Path parameter: id |
| DRIFT-002 | LOW | DOCUMENTATION_ONLY | MEDIUM | POST /users | Description update |
Finding DRIFT-001 Detail
- Baseline:
type: string - Current:
type: integer
Impact: Existing consumers sending UUIDs or alphanumeric strings will fail request validation at the gateway or application layer. This will result in 400 Bad Request or 404 Not Found errors for all legacy clients.
Evidence: Baseline OpenAPI spec (v1.0.2) defines id as string; current spec (v1.1.0-beta) defines it as int64.
- Recommendation: Revert the type change or implement a versioned path (e.g.,
/v2/users/{id}).
Connects securely to your tools. The creator never sees your data.
About this skill
Integration cycles break when API contracts drift silently from their documentation or previous versions. This skill automates the detection of breaking changes, structural mismatches, and behavioral shifts between baseline contracts and current implementations. It moves beyond simple text diffing to perform deep semantic and structural analysis of OpenAPI, GraphQL, and JSON schemas.
What it does
- Breaking change detection identifies modifications in requests or responses that will cause existing consumers to fail.
- Structural normalization resolves references and ignores non-functional changes like property ordering or whitespace to reduce noise.
- Behavioral drift analysis flags changes in data units, defaults, or pagination logic that schema validators often miss.
- Implementation verification compares live runtime responses against declared specifications to find undocumented fields or types.
- Impact scoring assigns severity levels and confidence scores to every detected discrepancy.
How it works
- Load inputs by providing baseline and current contracts or sharing a schema and a sample runtime response.
- Normalize and resolve all
$refpointers and inheritance structures to create a comparable flat inventory of endpoints. - Execute comparison across methods, parameters, body schemas, status codes, and security requirements.
- Generate report including a categorized list of findings with specific migration advice and CI/CD gate recommendations.
Frameworks & tools
Supports OpenAPI (Swagger), JSON Schema, GraphQL, and webhook payloads. Compatible with recorded REST responses, gateway definitions, and code-derived schemas.
Why this beats prompting it yourself
Generic prompts often fail to distinguish between additive changes and breaking ones, or they miss subtle drift in nullability and enum constraints. This skill uses a strict classification vocabulary and directional compatibility rules (Request vs. Response) to ensure high-precision audits without false positives from formatting changes.
Use cases
- Pre-deployment gates to determine if a schema change requires a new major version.
- Documentation audits to ensure the codebase actually matches the published Swagger UI.
- Legacy discovery to generate a baseline contract for an undocumented API from recorded traffic.
- Consumer impact analysis to provide specific migration steps for frontend teams when backend contracts change.
Known limitations
Cannot resolve external private $ref URIs without access. Semantic drift detection requires clear naming or documentation context to infer meaning changes.
Requires access to both baseline and current versions for drift analysis. Cannot resolve private external $ref links. Semantic drift is evidence-based and not guaranteed for vague naming.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 1 month ago
Permissions
No special permissions declared or detected