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?#
| Change | What to do in your client |
|---|---|
| New endpoints | Nothing. |
| New optional request fields or query parameters | Nothing. |
| New fields in responses and webhook payloads | Ignore fields you do not know. |
New keys inside details | details differs by source; never require a key to be present. |
| New signal types, subtypes, failure layers, providers and outcome ids | Treat unknown values as valid; fall back to a generic display. |
| New error codes | Handle unknown codes by HTTP status. |
Wording of message, title, reasons, evidence and notes | Show them to people; do not parse them. |
| Forecast numbers and source coverage | Expected: they change as data grows. |
| Plan limits and prices | Read 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.jsonalways describes what is running. Itsinfo.versionis1.0.0today. - 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.