https://api.proofage.net/v1. This page says what stays stable within v1 and how changes reach you.
What /v1 promises
Withinv1, ProofAge makes only non-breaking changes to the API and to the decision webhook unless the notice below has been given. A request that works today keeps working, and the fields you read today keep their names, types and meaning.
Breaking changes
These need notice:- removing or renaming an endpoint, a request field, a response field or a webhook field;
- removing or renaming a value of an enumeration, such as a status or a reason;
- changing a field’s type or meaning;
- tightening validation, so that a request accepted today is refused;
- changing a default, so that the same request behaves differently.
Non-breaking changes
These can ship at any time, and your integration must cope with them:- new response or webhook fields: ignore keys you do not know;
- new optional request parameters and headers;
- new values of an enumeration, such as a new verification status, decision reason or error code: handle a value you do not know, for example as “needs a person to look”;
- new endpoints;
- new webhook event types;
- a different order of keys in a JSON object, and a different
messagetext for an error (read thecode, not themessage).
Notice
A breaking change tov1 is announced at least six months before it takes effect, through:
- an entry in the changelog;
- an e-mail to the administrators of every workspace that uses the affected call;
DeprecationandSunsetresponse headers on the affected calls during the notice period, so a client can log them.
New security requirements
A new security requirement may become the default for new workspaces before existing ones are asked to adopt it. Existing workspaces keep working as they do until their owner turns the requirement on. Timestamped signatures work this way: every workspace accepts them, existing workspaces still accept a signature without a timestamp, and a workspace’s owner decides when to require them.SDKs
The server SDKs follow semantic versioning. Before 1.0, a minor release may change the SDK’s own interface; it never stops supporting av1 call that the API still accepts. Update them regularly so new optional features reach you.