TRaX Docs
reference

Versioning & compatibility

The Developer API is versioned in the path: everything lives under /v1. That prefix is a contract, not a build number — it's decoupled from the web studio's internal backend, so the API doesn't move under you when the app changes.

The compatibility promise

Within a major version (/v1), changes are additive and backward-compatible. We may, without a new version:

  • add new endpoints;
  • add new optional request parameters;
  • add new fields to a response object;
  • add new error.code values;
  • add new enum values to an existing field.

We will not, within /v1:

  • remove or rename an endpoint, field, or error.code;
  • change the type or meaning of an existing field;
  • make a previously optional request parameter required;
  • change the meaning of an existing error.code.

Write your client to tolerate additions

Because additive changes ship within /v1, a well-behaved client:

  • ignores unknown response fields rather than failing to parse them;
  • treats error.code as an open set — branch on the codes you know, and have a sensible default for a code you don't recognize;
  • doesn't depend on field ordering or on the absence of a field;
  • pins to /v1 in its base URL and lets new fields arrive for free.

If you generate a typed client from the OpenAPI spec (see the SDK quickstarts), regenerate it periodically to pick up new fields — but an old generated client keeps working against /v1.

Breaking changes → a new major version

A change that would break existing callers only ships under a new path version (/v2), never inside /v1. When that happens, /v1 and /v2 run side by side for an overlap window so you can migrate deliberately. We'll announce deprecations with lead time; /v1 won't disappear out from under you.

Environments

Environment Base URL Status
Development https://api-dev.traxstreaming.live/v1 Live now (read endpoints; writes gated — see Roadmap)
Production https://api.traxstreaming.live/v1 Planned once the surface is stable

Only the host changes between environments — the /v1 contract is identical. Build against /v1 on dev today and you'll move to production by swapping the hostname.

The machine-readable spec at /v1/openapi.json carries its own info.version (semver), which tracks additive revisions within /v1. The path version (/v1) is the compatibility boundary; the spec's info.version just tells you how recent the document is.