oasdiff breaking: catch Sume OpenAPI changes in CI

Short answer

Save a copy of the Sume OpenAPI document in your repository and run oasdiff breaking between that snapshot and the live spec in CI. The oasdiff README says the command shows only the changes that break existing API clients, and that specs can be local files, URLs, JSON or YAML. The Sume spec is a public route, GET /v1/openapi.json, so the check needs no API key.

Why compare specs at all

Your client code is generated from, or at least written against, a spec snapshot. When the live spec moves, you want to find out on a schedule, not from a production error. A diff that lists only breaking changes keeps the signal clean: a new optional field in a response is not a break for a client that ignores unknown fields, but a removed field or a newly required request parameter is.

Sume's docs call the live OpenAPI and the API reference the source of truth for request and response fields, and the TypeScript SDK's generated operations come from the same schema.

The CI step

Fetch the live document, then diff. oasdiff also accepts URLs directly, so you can point the second argument at the live address, but downloading first gives you a file to attach as a build artifact when the check fails.

Run oasdiff breaking --help to see how to turn findings into a failing exit code for your pipeline; the README points to its customization docs for check configuration rather than listing every flag on the front page.

curl -sSf https://api.sume.com/v1/openapi.json -o live-openapi.json
oasdiff breaking openapi.snapshot.json live-openapi.json

What a green result does not tell you

A spec diff covers shape, not behavior. A change in how retries, limits or webhook delivery work will not appear there. Rate limits depend on the plan, and the read multiple is a deployment setting, so the response headers remain the authority. Keep your contract tests on real responses, and treat the spec diff as an early warning.

When the diff does report a break, update the snapshot in the same pull request as the client change, so the snapshot always describes the spec your code was written against. Schedule the job daily rather than only on pushes, since the service changes independently of your repository.

Scope the noise

Run the check on the paths you actually call. A spec that covers many products will produce findings for routes you never use, and a noisy check is a check people learn to ignore. Start with the routes in your integration, such as the generation submit, the jobs status and result routes, and the webhook-related account routes, and widen from there.