Versioning & deprecation
The API is versioned by path segment: everything documented here lives under
/api/v1/*. There is one version today — 1.0.0 — and no breaking changes
have shipped since it launched.
Every response carries the negotiated version:
| Name | Type | Description |
|---|---|---|
X-API-Version | string | The version that served this response, e.g. 1.0.0. |
Deprecation signal
When a route is slated for removal, responses from it start carrying:
| Name | Type | Description |
|---|---|---|
X-API-Deprecated | string | "true" when the route you called is deprecated. |
X-API-Sunset | string | The date the route stops working, when set. |
Nothing under /api/v1/* is deprecated as of this writing. Check these two
headers in your integration’s response handling so a future deprecation
shows up as a signal, not a surprise outage.
Scoping
Every request is scoped to a project via project_key (venture_key is
accepted and returned as a legacy alias) — see the API overview for
how that’s resolved. Versioning and scoping are independent: a
project_key/venture_key mismatch fails with 403/404
(Errors), unrelated to which API version you’re calling.
Additive changes
Additive changes — a new optional field, parameter, or alias that doesn’t
remove or repurpose anything existing — ship without a version bump or a
deprecation window, since no 1.0.0 integration can break from them.
project_keyalias forventure_key. Every request and response field namedventure_keynow also accepts/emitsproject_keywith the same value.venture_keyis unchanged and continues to work;project_keyis simply the new primary name. Supplying bothproject_keyandventure_keyon the same request with different values is rejected with400(project_key and venture_key conflict) rather than silently picking one.