OpenAPI Breaking Change Detector

Compare two OpenAPI/Swagger documents and identify breaking and non-breaking API contract changes between them.

What it checks

• Removed or renamed endpoints and operations
• Parameter, request-body, and response schema changes (type changes, new required fields, removed fields)
• Authentication/security scheme changes
• Non-breaking additions (new optional fields, new endpoints)

The Actor performs a live comparison through Sentinel Verify.

Pricing

This is a paid, pay-per-event Actor: $0.12 per completed comparison.

Exactly one openapi-diff event is charged per run, only after a real result exists (success or a useful partial). There is no charge for invalid input, a URL blocked by the public-network policy, or a run that fails before a result is produced.

Input

• beforeUrl (required): HTTPS URL of the earlier OpenAPI/Swagger document.
• afterUrl (required): HTTPS URL of the newer OpenAPI/Swagger document.

Example input:

{
  "beforeUrl": "https://example.com/openapi-v1.json",
  "afterUrl": "https://example.com/openapi-v2.json"
}

Output

The default dataset receives one result envelope per comparison; RUN_SUMMARY in the default key-value store records processing, delivery, billing, and dependency totals.

Representative abbreviated output:

{
  "status": "success",
  "result": {
    "breakingCount": 2,
    "nonBreakingCount": 5,
    "changes": [
      {"severity": "breaking", "type": "API_PARAMETER_REQUIRED_CHANGED", "path": "/v1/orders", "method": "POST"}
    ]
  }
}

restricted means one of the URLs was rejected locally before calling Verify — beforeUrl is checked first, so if it fails the result names beforeUrl; otherwise afterUrl is checked next. unreachable means a URL's hostname could not be resolved. dependency_unavailable means Verify was temporarily unavailable.

How it works

This Actor is a thin wrapper around Sentinel Verify's POST /v1/utilities/api-schema-diff endpoint. Each URL is checked locally against API-IFY's public-network policy, beforeUrl first and then afterUrl, before either is sent to Verify.

Limitations

• Public HTTPS URLs only, port 443, no embedded credentials; private, loopback, link-local, metadata, reserved, and CGNAT targets are rejected.
• Comparison availability depends on Sentinel Verify.

Privacy and security

Both URLs are sent to Sentinel's live Utility API (/v1/utilities/api-schema-diff) for analysis after local public-network validation. Results are stored in the customer's Apify run dataset and summary store. VERIFY_API_KEY is an operator-managed Actor secret — a scoped utilities:read Intelligence API key sent as a bearer token on every request, the same credential mechanism used by any other Utility API consumer; VERIFY_BASE_URL is an operator setting, not an Actor input.

Support

For a reproducible support request, provide the Apify run ID, result itemId, and status. Contact Sentinel Signal Systems through the support link on the Actor page.