Versioning and deprecation

The MobileValidate API is versioned in the URL path. v1 (https://api.mobilevalidate.com/v1) is the current, stable version. This page explains which changes can happen within v1, what your client must tolerate, and how we retire anything.

#What changes can happen within v1?

Within v1, changes are additive only. We may, without notice:

• add new endpoints, and new HTTP methods on existing paths;
• add optional request fields, query parameters and headers (existing requests keep the same meaning);
• add fields to response objects and webhook payloads, including nested objects;
• add new error codes, new values to enums such as status, reason and attribute values, and new check codes in GET /v1/services;
• add new webhook event types (you only receive the types your endpoint subscribes to);
• change human-readable text: error message and suggestion, descriptions and documentation;
• change the order of fields in JSON objects, and the format of opaque IDs (treat IDs as strings);
• raise limits. Lowering a documented limit counts as a breaking change.

Every such change is listed in the changelog.

#What must my client tolerate?

To keep working through additive changes, a v1 client should:

• ignore unknown fields in responses and webhook payloads, rather than failing to parse them. Don't use strict deserialization that rejects extra properties;
• handle unknown enum values. For example, treat an unknown status like a non-conclusive result, and an unknown attribute value as "unknown";
• branch on error.code, never on error.message, and fall back to the HTTP status for codes it doesn't know (see errors);
• ignore webhook event types it doesn't handle, returning 2xx so they aren't retried;
• not depend on field order or on the length or format of IDs.

#What counts as a breaking change?

Removing or renaming an endpoint, field, parameter or enum value; changing a field's type or meaning; making an optional request field required; changing authentication; changing an HTTP status for an existing situation; or lowering a documented limit.

Breaking changes only happen in a new major version (for example /v2). v1 keeps working unchanged for at least 12 months after the new version and the v1 retirement date are announced, and both versions run side by side during that time.

#How are deprecations announced?

When we deprecate an endpoint, field or parameter:

1. We publish a changelog entry with the tag "API" (also in the RSS feed), naming what is deprecated, what replaces it and the sunset date. The sunset date is at least 12 months after the announcement.
2. We e-mail the contacts of the accounts that use it.
3. The documentation marks it as deprecated.
4. Responses that use it carry the standard headers:

Deprecation: @1790812800
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Link: <https://mobilevalidate.com/changelog>; rel="deprecation"; type="text/html"

Deprecation (RFC 9745) gives the date the deprecation took effect as a Unix timestamp. Sunset (RFC 8594) gives the date after which the endpoint or field may stop working. The values above are an example: deprecated on 2026-10-01, sunset 12 months later. Log these headers in your client so a deprecation never goes unnoticed.

Until the sunset date, deprecated endpoints and fields keep working exactly as before.

#Are there exceptions?

If a change is required to fix a security vulnerability or to comply with the law, we may have to act with less than 12 months' notice. In that case we give as much notice as we can and explain the reason in the changelog.

#How are the SDKs, CLI and OpenAPI file versioned?

• The SDKs, the CLI and the MCP server follow semantic versioning. A new major version of a package is released only for breaking changes to the package itself, and each release lists its changes.
• The OpenAPI specification carries the API version in info.version (1.x.y for v1). A minor or patch increase never contains a breaking change.

#Where can I see the current state?

• Changelog and its RSS feed for every API, SDK and documentation change.
• System status for availability and incident reports.