Versioning

The REST API is versioned in the path: everything is under /v1. This page explains what stays stable within v1, which changes can happen without a new version, and how to write a client that tolerates them.

What stays stable in v1?#

Within v1 the aim is that these do not change in ways that break a client:

  • Existing endpoint paths and methods.
  • Existing request fields and query parameters, and what they mean.
  • Existing response fields, their names and types.
  • The error envelope and existing error codes.
  • The webhook signature scheme (Disrupt-Signature, t=...,v1=...) and existing event types.

Fields that were renamed in the past stay available under their old names, for example trips in exposure requests and trip_id in exposure results.

What can change without a new version?#

ChangeWhat to do in your client
New endpointsNothing.
New optional request fields or query parametersNothing.
New fields in responses and webhook payloadsIgnore fields you do not know.
New keys inside detailsdetails differs by source; never require a key to be present.
New signal types, subtypes, failure layers, providers and outcome idsTreat unknown values as valid; fall back to a generic display.
New error codesHandle unknown codes by HTTP status.
Wording of message, title, reasons, evidence and notesShow them to people; do not parse them.
Forecast numbers and source coverageExpected: they change as data grows.
Plan limits and pricesRead them from GET /v1/plans and the headers.

What would need a new version?#

Removing or renaming a field or endpoint, changing a field's type or meaning, making an optional parameter required, or changing the signature scheme. There is no v2 today. If one becomes necessary, the intent is to ship it under a new path prefix and announce it, with any end date for /v1, in the changelog ahead of time.

The four severities (minor, moderate, severe, extreme) and five risk levels (none to severe) are fixed in v1.

How are changes announced?#

  • Every change that affects integrations is listed in the changelog with its date.
  • The OpenAPI spec at /openapi.json always describes what is running. Its info.version is 1.0.0 today.
  • There are no version headers or dated API versions to pin. The path is the version.

MCP server versions#

The MCP server negotiates the protocol version with each client (2025-06-18, 2025-03-26 or 2024-11-05). Tool names and required inputs follow the same rules as REST fields: new tools and optional inputs can be added, and the aim is not to remove or rename existing ones.

Last updated 2026-11-18. Questions or a mistake on this page? Contact us.