Versioning

Trybe runs a single, unversioned API surface. There is no /v1 prefix in the path, no Trybe-Version request header, no version pinning on the token. Every caller is on the current API at all times. This page explains what we keep stable on that surface, what we don't, and how breaking changes are managed.

The contract

The shape of the public API — operations, schemas, and the names any generated client derives from them — is governed by a strict backwards-compatibility contract. This is the summary every consumer should know.

What's locked

We will not change any of the following without an explicit, communicated break:

Operation IDs. Every operation has a stable operationId (e.g. listSites, getCustomer). These become method names in any client generated from the spec. Once an operationId is published, it is permanent.
HTTP method and path. GET /sites will always be GET /sites. We will not move an operation to a new path or method.
Required parameters. The set of required path, query, header and cookie parameters on each operation is fixed. We will not add a new required parameter to an existing operation.
Schema titles. Every JSON schema has a stable title (e.g. Site, PaginationMeta, ValidationFailed). Once published, titles never change — even if we move, split or merge the schema internally.
Request body and 2xx response titles on each operation — these become interface names in any generated client, so consumers import them by name.

A CI check on every commit to the OpenAPI definitions diffs the rebuilt spec against a baseline and refuses to merge any of these changes.

What's free to change

Additive changes are welcome and ship in normal releases:

New operations, including new paths.
New schemas and new optional fields on existing schemas.
New enum members on existing enums.
New optional parameters on existing operations.
New error responses, examples and descriptions.
Loosening a required response field to optional — consumers already handle the field being present and won't break if it sometimes isn't.

If you write a client that ignores unknown fields and unknown enum values, you can pick up new features as they ship without any code change.

What's not stable

A few things are explicitly outside the contract — don't write code that depends on them:

Field descriptions and example values. We rewrite descriptions to improve clarity. Don't parse them.
The exact text of message strings in error responses. Branch on the HTTP status code, not the message body. See errors.
Endpoints flagged internal in the OpenAPI spec. A handful of operations exist for our admin app and aren't part of the public contract. Don't integrate with them; we will change them without notice.
Response ordering when the endpoint doesn't document a sort. If a list endpoint doesn't promise a sort order, don't depend on the order you observe empirically.
Pagination cap values. The maximum per_page an endpoint accepts can rise (it won't drop without notice). Read meta.per_page instead of hardcoding the cap. See pagination.

When a break is genuinely required

Some changes — a security fix, a regulatory deadline — cannot be additive. When that happens:

The break is documented in sdk-baseline/compat-exceptions.json with an approval and a consumer-communication task.
Affected integrators are emailed in advance of the change going live.
The CI check is updated so the new shape becomes the baseline.

If you're an integrator and you'd like to be on the notification list for these events, ask your Onboarding Manager to add you.

Defensive integration patterns

These cost nothing to adopt and protect you from a category of "we shipped a change you didn't expect" surprises that, in our experience, every API eventually delivers: