Review an API change

See how a response changed, how risky it is, and accept or ignore it.

In short

{{brand}} remembers the shape of each endpoint's answer as its contract. When a later answer differs - a field removed, a type changed, a new error status - it makes a change report with a risk level. You accept the change as the new contract, or ignore it.

Before you start

Who: reading reports needs View. Accepting or ignoring a change needs Edit.
Plan: change intelligence comes with plans that include it (Plan & usage › Features).
First: run the request at least once so a contract exists.

Steps

Open "Watch" › "API changes" › "Seen in runs", or follow the "API change detected" link after a request.
Read the risk level and each reason behind it.
Compare the previous and current contracts, and check affected requests and findings.
Choose "Accept new baseline" if the new contract is correct and should become the baseline, or "Ignore change" to keep the existing one.

Result: an accepted change is what later runs are compared against; an ignored one keeps the old baseline.

Read a change report

Below are each difference with before and after, the two versions side by side, authentication and status findings, and the risk calculation. Risk is a score from factors such as a removed field, a changed type, a new error status or a repeated slowdown. It shows as low, medium, high or critical, with each factor and its points listed.

When the run behind a report failed, the report opens with what failed and what changed just before. It also shows the likely cause with its confidence, what else is affected and the next action. Choose a board and press "Create bug" to file a card with the evidence filled in.

Good to know

The first completed response for an endpoint becomes version 1 of its contract. URLs with IDs, such as /users/10 and /users/20, share one contract.
It detects fields added, removed, made required or optional or retyped (including nested ones). It detects status codes or important headers added or removed. It also detects repeated slowdowns or size growth when there is enough history, success turning into an error, and authentication or validation changes.
Change intelligence comes with plans that include it.
On a phone each change in the list is a card, and a card opens its report.

Watch a request for changes with a change monitor

Open "Watch" › "Monitors", press "New monitor" and, under "What it checks", choose "One request".
Give it a "Name", choose the "Request" and "How often".
Press "Create monitor".

Result: the monitor is listed under "Monitors" with its state and "Next check". Each check is a run of the saved request like any other, so when the answer's shape changes, a change report appears in "Watch" › "API changes" › "Seen in runs", to accept or ignore as above.

With no saved request in the open project, the "Request" list says "This project has no saved requests yet". Until a request is chosen, "Create monitor" says "Choose a request or a suite to check first."
The switch in the "On" column pauses the monitor and turns it back on. A paused monitor shows "Paused" and makes no checks.
"Daily history", at the top of the monitor's sheet, shows the uptime and the 95th percentile of every UTC day for 30 days, 90 days or a year. It is kept long after the 30 days of individual checks.
"Delete monitor" in the row's menu stops its checks; "Undo" on the message brings it back.

If something goes wrong

Every run makes a new candidate: the answer changes each time (for example a timestamp field). Accept the shape once; an identical repeat creates nothing.
Accepting a change by mistake: later runs compare against it. Accept the right version again.
"This change has already been reviewed." and "Choose Accept or Ignore.": reload the page.
"A failed execution without a successful baseline cannot become the accepted contract.": run the request until it answers, then accept.

/help/api-testing/change-history
/help/api-testing/api-changes
/help/api-testing/executive-summary