Skip to main content

​
Current contract

The published Partner API is versioned under /v1. The canonical OpenAPI document also tracks the current public contract version in info.version.

​
Compatibility posture

Trailflow treats v1 as additive-first. That means:
  • new fields may be added without changing existing field semantics
  • new endpoints may be introduced under /v1
  • new enum values may be added when the workflow expands
Partners should ignore unknown fields and handle additive enum growth safely.

​
What counts as a breaking change

These changes require explicit partner coordination before release:
  • removing a field or endpoint
  • renaming a field
  • changing the meaning of an existing field
  • changing the required authentication or idempotency rules for an existing route

​
Release communication

Trailflow tracks public contract changes in the Partner API changelog. Any change to the canonical OpenAPI contract must ship with an updated changelog entry and regenerated docs artifacts.

​
Integration guidance

To stay compatible over time:
  • prefer tolerant JSON parsing for additive fields
  • pin workflow assumptions to documented semantics, not field order
  • monitor the changelog before production rollout windows
  • include requestId values when reporting suspected contract regressions