Skip to main content
The Tripwire API is versioned in the URL path. The current major version is v1, and every public endpoint lives under /v1/. 
https://api.tripwirejs.com/v1/sessions/sid_...
Version numbers in the path signal major, breaking releases. Inside a major version, the API evolves continuously — we add fields, enum values, and endpoints without bumping the version. Pinning to /v1/ gives you a stable contract for the life of that major.

​
What’s additive (safe to adopt)

The following kinds of changes can appear inside a major version without notice, and your integration should handle them gracefully:
  • New endpoints. New paths under /v1/ may be added at any time.
  • New optional request fields. New parameters on existing endpoints are always optional — existing requests continue to work unchanged.
  • New response fields. Additional fields may be added to any response object. Treat response shapes as open — deserialize the fields you care about and ignore the rest.
  • New enum values. New values may be added to existing enums (verdict categories, attribution facets, error codes). Don’t switch on a closed set; include a default branch.
  • New error codes. The error code namespace grows over time. Branch on the category prefix (auth.*, validation.*, rate.*) when you want broad handling; branch on the specific code only where your UX needs the precision.
  • New webhook events. For Gate webhooks and any future webhook surfaces, new event types may be delivered alongside existing ones. Unknown event types should be acknowledged and ignored, not rejected.
In short: unknown fields, values, and events should never crash your integration. Plan for them from day one.

​
What’s breaking (announced in advance)

Changes that could break an existing integration get a version bump or, for surgical cases, a deprecation notice with a migration path. Examples of what counts as breaking:
  • Removing a field from a response
  • Renaming a field
  • Changing a field’s type (string → number, nullable → non-nullable, etc.)
  • Changing the semantics of an existing field or enum value
  • Removing an endpoint
  • Making a previously-optional field required
  • Changing authentication requirements on an endpoint
  • Changing the default behavior of an endpoint in a way that surprises existing callers
We do not ship these silently on /v1/.

​
Deprecation and sunset

When a specific endpoint, field, or behavior needs to go, we follow a staged process inside the current major:
  1. Announcement. The deprecation is published in the Changelog, highlighted in the dashboard for affected organizations, and (for material changes) emailed to the organization owner on record.
  2. Grace period. The old behavior continues to work alongside the new one. The documented sunset date is never less than 90 days from the announcement for live-mode behavior; test-mode deprecations may be shorter.
  3. Sunset. After the grace period, the old behavior is removed. Requests that still use it return a 410 Gone (or, for fields, the field is simply absent from responses).
During the grace period, deprecated fields are clearly marked in the API Reference pages and in OpenAPI schema output.

​
Pinning to a version

The only version pin you need is the /v1/ in the URL. As long as you keep calling /v1/, you’ll stay on the stable major contract. We do not offer dated API versions (e.g. API-Version: 2025-04-16) — additive evolution inside /v1/ is the design. If that ever changes, the current /v1/ contract is what we’d continue to honor until a /v2/ release.

​
When a new major version ships

If we release /v2/, three things will be true:
  • The announcement will be early. Major versions are announced in the changelog, the dashboard, and (for customers on v1) by email at least 180 days before v1 is scheduled for sunset.
  • Both versions will run in parallel. Your /v1/ integration keeps working through the overlap.
  • A migration guide will be published. Every breaking change will be listed, with the equivalent /v2/ call for each /v1/ pattern.
We do not plan to retire /v1/ in the foreseeable future. This section exists so the policy is clear if and when we do.

​
SDK versioning

The server SDKs follow their own semver release cadence, independent of the API version:
  • Patch releases (x.y.z → x.y.z+1) — bug fixes and dependency updates. Safe to upgrade without reading the changelog.
  • Minor releases (x.y.z → x.y+1.0) — new endpoints, new helper methods, new SDK-level features. Backwards-compatible with existing code.
  • Major releases (x.y.z → x+1.0.0) — breaking SDK changes: renamed methods, changed return types, dropped support for old Node/Python/Go versions. Migration notes are published with each major.
An SDK major can ship without an API major, and vice versa. The SDKs track API changes closely — when the API adds a new endpoint or field, the next SDK minor typically exposes it. When a breaking API change ships under /v2/, the SDK will bump to a matching major. Pin SDK versions in your dependency manifest the way you pin any other library. Review changelogs before upgrading across major boundaries.

​
Watching for changes

  • Changelog — the authoritative list of API and SDK changes.
  • OpenAPI spec — the shape-of-truth for endpoints, fields, and enums. Diff it across releases if you need to automate detection of new fields or codes.
  • Dashboard notices — material deprecations affecting your organization show up in the dashboard’s announcement area.

​
What’s next

Errors

Branch on category prefixes, not specific codes.

Pagination

Cursor opacity and why not to parse.

Changelog

Dated list of API and SDK changes.

Authentication

Key lifecycle across live and test environments.