Definition versions
Pin each execution to the API definition your application has reviewed. A source identifier names the API; its definition version identifies a particular saved contract and collection plan.
On this page
Copy the full definition version from the API detail page. The request examples use a 64-character definition hash in expected_version. Keep it in application configuration alongside the source identifier, rather than selecting whichever version happens to be active at execution time.
Send the reviewed version#
The following request body illustrates the version check and a bounded input. Replace the placeholder with your saved definition hash and follow your API's supplied request example:
{
"expected_version": "<your-saved-definition-version>",
"input": {
"max_pages": 1,
"detail_limit": 0
}
}
Pinning catches disagreement between your application configuration and the active definition. It does not freeze the website, preserve its records, or guarantee that future executions succeed. Use the returned summary to evaluate each run.
Handle a version conflict#
When a request reports a version conflict, stop that execution path and open the API's current definition and version history. Compare the active version with the version deployed in your application.
Do not remove expected_version or silently replace it with a newly fetched value. Either action skips the contract review the check protects. Refresh stale connection details, establish which change occurred, and update application configuration only after validating the new contract. See errors and retries for request failures and uncertain outcomes.
For an explicit execution of a previously accepted revision, the run API supports definition_version instead of expected_version. Never send both fields, including a field set to null. This applies saved collection rules to the live website; it does not retrieve a historical website snapshot or restore an old version as active. An inactive candidate is not an accepted revision.
Review a candidate revision#
When revision controls are available for the API, build a candidate from the saved request and inspect its comparison with the active version. A validated candidate remains inactive until it is explicitly activated.
Review changes to output fields, types, required values, input controls, and collection limits. Recheck application assumptions even when no REST schema or input changes are detected: source behavior and returned values can still differ. If an MCP connection is in use, refresh its versioned tool name after changing the definition.
The workspace checks the comparison and active version again during activation. If either changed during your review, refresh the candidate review before proceeding. After activation, read back the current connection details before updating your consumer.
Migrate the consumer deliberately#
Treat these changes as integration work:
| Change | Consumer action |
|---|---|
| Added optional field | Check unknown-field handling and decide whether to store it |
| Renamed or removed field | Update mappings and required-field checks |
| Changed type, unit, or identity | Review parsing, comparisons, joins, and deduplication |
| Changed input limits or collection scope | Recheck request budgets and coverage assumptions |
Test representative records against the saved schema, including missing values. Keep the previous configuration and its evidence for diagnosis. Any historical execution still depends on current source access and the saved definition's availability.
Coordinate the version change with scheduled consumers, make a bounded request following the quickstart, and check its full response before restoring normal volume. Retain the definition version with stored results so later investigations can distinguish contract changes from source changes.