Versioning & Deprecation

The InvesTeam API is URI-versioned and evolves additively within a major version. Understanding the versioning rules — especially that status enums are open — is what keeps your integration from breaking when the API grows. This page states the rules and the deprecation policy.

How is the InvesTeam API versioned?¶

The API is URI-versioned at /api/v1. The version in the path is the public contract version, decoupled from any individual service's internal versioning. Within a major version, changes are additive-only: new response fields, new endpoints, and new enum values that clients already treat as open sets are non-breaking. Removing or renaming a field, or narrowing a type, is a breaking change and would require a new major version (/api/v2).

The practical rule for your client: tolerate unknown fields. A new field in a response body must not break your parser.

Why should I treat statuses as an open set?¶

Because the API may add new status and transcript kind values within v1 without a version bump. status (on briefs, orchestrations, and executions) and transcript kind are documented as open enums. Map any value you do not recognize to a safe "keep polling / show generic" state — never crash on it.

A concrete pattern: if an execution status is not one of the terminal values you know (completed, failed), treat it as still running and keep polling. See the async model.

How does InvesTeam deprecate endpoints?¶

When an endpoint is superseded, it does not disappear without warning. A deprecated endpoint returns a Deprecation: true header and a Sunset: <date> header for at least 90 days before removal, and the aggregate OpenAPI marks it deprecated: true. Watch for those headers on your responses and migrate before the sunset date.

Watch response headers for Deprecation and Sunset, and re-fetch the OpenAPI spec periodically — a field marked deprecated: true there is your earliest migration signal.

What about pagination on `GET /api/v1/sessions`?¶

GET /api/v1/sessions is designed to accept limit and cursor query parameters, but they are honored only once server-side pagination ships. Until then the endpoint returns the full owner-scoped list, newest-first, and ignores those parameters. Write your client to tolerate either shape — a paginated response later is an additive change, not a break.

Where next?¶

For the error envelope your client parses, see the Error Reference. For the machine-readable contract, see the OpenAPI spec.