API versioning policy

Every API response carries X-Veriastra-Version. Today it is 1 on every endpoint.

You can call the API two ways: https://veriastra.com/api/v1/… (pinned) or https://veriastra.com/api/… (unpinned, always the current version). Both route to the same code today, and that is the point worth understanding: pinning does not freeze behaviour by itself. It becomes protection the moment v2 exists, because the unpinned path will move to v2 and the pinned one will not. If you are writing an integration you intend to leave alone, pin it now.

These are additive. If your client ignores fields it does not recognise — which it should — none of them can break you:

• Adding a new endpoint.
• Adding a new field to a response object, including new entries in signals and new rows in rows.
• Adding a new optional request parameter with a default that preserves current behaviour.
• Adding a new value to a list we already document as open-ended (a new sanctions source, a new lineType, a new error code).
• Making an answer more accurate: a bigger corpus, a better match, a corrected score. The shape stays; the content is supposed to improve.
• Performance, rate-limit ceilings raised, new response headers.

The practical consequence: do not write code that fails on an unknown field or an unknown enum value, and do not assert on an exact score. We will keep adding to all three.

These are breaking, and we will not make them to v1:

• Removing or renaming a field, an endpoint, or an error code.
• Changing a field's type, or the meaning of an existing value.
• Making an optional request parameter required, or narrowing what an existing one accepts.
• Changing the HTTP status for a condition we already return one for.
• Changing what a call costs in credits, upward.
• Changing the signing scheme for webhooks or result receipts.

• 12 months. When a version is deprecated it keeps working for at least twelve months from the announcement. We do not shorten this for convenience.
• You are told directly. Every account with a request against the affected version in the previous 90 days gets an email. Deprecation is not something you should have to discover by reading our changelog.
• The API tells you too. Responses from a deprecated version carry Deprecation and Sunset headers (RFC 8594), so a client can log the warning without anyone reading email.
• Security is the exception. If a change is required to close a vulnerability we will make it as fast as the vulnerability demands, and explain it afterwards. We would rather break an integration than leave a hole open, and you should want the same from any vendor holding your data.

Naming the gaps is more useful than implying there are none:

• The data itself. Sanctions lists, carrier assignments and company registers change because the world changes. A name that matched last week may not match today. That is the product working, not a breaking change — see coverage for what we hold and when it was last refreshed.
• Scores and thresholds. Fraud and risk scores are tuned continuously. Treat them as a signal to threshold on, not a stable number to compare across time.
• Undocumented behaviour. If it is not in the OpenAPI spec or the docs, it is not a contract. Field ordering, whitespace, and the exact wording of a human-readable message are examples.
• Endpoints marked beta. They are labelled as such in the docs and may change with shorter notice. None are today.

Quote the X-Request-Id from the response. It identifies the exact call in our logs, which turns a support thread from a description of a problem into a lookup. Write to [email protected].