Versioning

The Pinch API version is encoded in the URL path. The current major version is v1:

POST https://api.pinch.ai/v1/order

There is no Pinch-Version header. The path is the contract.

What counts as a breaking change

A change is breaking if it requires you to update your integration to keep working. These trigger a new major version:

• Removing or renaming a field in a request or response
• Changing a field's type (e.g. number → string)
• Changing the meaning of an existing enum value
• Removing or renaming an endpoint
• Tightening a previously-optional field to required
• Changing the URL structure of an endpoint

A change is non-breaking if your existing code keeps working. These ship inside the current major version without warning:

• Adding new optional fields to requests
• Adding new fields to responses (your code should tolerate unknown fields)
• Adding new endpoints
• Adding new enum values to a field your code is parsing
• Performance, error-message, or scoring-model improvements

Treat your client as additive-tolerant: if a response contains a field you don't recognize, ignore it. Pinch will add fields over time.

Deprecation policy

When Pinch needs to ship a breaking change:

1. The new behavior lands behind a new major version (e.g. /v2/...).
2. The old version stays online for a 12-month deprecation window.
3. During the window, Pinch emails the technical contact on file at least 90 days, 60 days, 30 days, and 7 days before sunset.
4. Each response from the deprecated endpoint includes a Deprecation header with the sunset date in HTTP-date format.
5. After the window, the deprecated endpoint returns 410 Gone with a pointer to the migration guide.

Pinch does not silently change behavior on an existing endpoint within a major version.

Reading the Deprecation header

HTTP/1.1 200 OK
Deprecation: Tue, 31 Dec 2026 23:59:59 GMT
Sunset: Tue, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.pinch.ai/api-reference/migration-v1-to-v2>; rel="successor-version"

If your alerting can read response headers, set an alert on any non-empty Deprecation value. That gives the team a year of lead time to migrate.

Model and scoring changes

The Pinch Assessment score (0–100) and the underlying ML model evolve continuously. Scoring improvements are explicitly not versioned — Pinch ships them inside the current major version without notice. The contract is the response shape and the meaning of decision, subDecision, and decisionReason. The exact score value for a given input may shift over time as models retrain.

If you have a downstream rule that hard-codes a score threshold (e.g. "block above 75"), tune it periodically against your actual data rather than treating it as permanent.

Major versions roadmap

Version	Status	Notes
v1	Current	Stable, recommended for all new integrations
v2	Not yet released	Will be announced via the changelog and email

See also

• Changelog — every API and dashboard release
• Errors — how 410 Gone looks on deprecated endpoints
• API overview — base URL and conventions