Skip to main content

Entrupy API Versioning

The Api-Version header you send when contacting the Entrupy API controls the format we expect for your requests (e.g., required headers, JSON keys in POST requests, enabled features) and also determines the format of the response sent to your clients.

When you create a webhook using the Entrupy API, the Api-Version you use will also determine the format for future updates sent to your webhook endpoint.

Whenever we make a breaking change to the API or to webhook events, we will release a new API version. Your existing requests and webhook endpoints should continue to work without changes, provided you adhere to the guidelines below.

Backwards Compatible Changes​

Backwards-compatible changes may be made at any time for consumers of existing API versions. These changes could affect the exact format of Entrupy API responses and webhook events. Please verify that your code can handle the following changes without issues:

  • Adding new keys to any dictionary/object in an existing API response or webhook event.
  • Adding new elements to any array, as long as the type of individual elements remains the same.
  • Changing the order of keys in a JSON object or the order of elements in an array.
  • Changing the specific HTTP status code returned for an error, unless a specific HTTP status code was explicitly listed in the API documentation. For example, a generic 500 error could be changed to another 4xx or 5xx series error. Your code should generally fall back to default error handling for any non-HTTP 200 status.
  • Adding new events that trigger a webhook, as long as the payload format remains unchanged.
  • Adding new API routes to the Entrupy API.
  • Adding new optional inputs to existing API routes (e.g., headers, JSON request parameters, GET request arguments).

We may also change any opaque strings not clearly marked as external identifiers. Examples include:

  • Certificate URLs for authentic items.
  • Image URLs.
  • Specific reasons given for an "invalid" or "not supported" result.
  • Human-readable display strings (e.g., brand name, result name, timestamp display string). Always use the id or epoch field for persistent identifiers, not the display field.
  • Error messages.

If you are storing any string from our API in a database, we recommend using a VARCHAR type, as some strings (like presigned image URLs) can be very long and may change. If you must set a length limit, allow at least 4096 characters for image URLs; for other strings, a lower limit (e.g., 1024 characters) may be acceptable.

Breaking Changes​

The following changes will only be made with a new API version:

  • Any changes to the data types of existing values.
  • Deleting or renaming existing API routes.
  • Deleting or renaming keys in a dictionary/object from the API response.
  • Adding new required API headers, request JSON parameters, or GET request parameters.
  • Deprecating existing API headers, request JSON parameters, or GET request parameters.