Versioning

The version lives in the path. Every endpoint today sits under https://api.tase.app/v1, and that prefix is the contract: while you stay on /v1, we will not remove an endpoint, remove a response field, rename anything, or change the type or meaning of a field that is already there.

There is no date-based version header and no per-request version parameter. One path, one contract. If we ever need to break it, the break arrives as a new path, not as a silent change under your feet.

Backwards-compatible changes

These changes can ship at any time, without notice, inside /v1. Build so that none of them can break you.

• New endpoints added under /v1.
• New optional request fields: anything you were already sending stays valid, and the default behaviour of an existing field does not change.
• New response fields added to an existing object. Existing fields keep their name, type and meaning.
• New enum members in permissive positions: a new finish_reason, a new error code, a new model id in GET /v1/models. Treat any unknown value as "something I do not handle yet", not as a fatal error.
• New models appearing in the model list, and new optional headers on a response.
• Wording changes in the human-readable error message field. Branch on type and code, never on message text.

Breaking changes

A change is breaking if a correct integration written against the documented behaviour could stop working. We ship these behind a new version path, not inside /v1.

• Removing or renaming an endpoint, a request field, or a response field.
• Changing the type of an existing field, or changing what an existing value means.
• Making a previously optional request field required, or tightening validation so a request that used to be accepted is now rejected.
• Removing a member from an enum you are expected to send us, or changing the shape of the error object.
• Changing a default: if you never set a parameter and the behaviour you get changes, that is breaking even though nothing in the schema moved.

Writing a client that survives

1. 1

   Decode permissively

   Ignore unknown fields rather than rejecting the payload. In TypeScript, avoid schema validators configured to strip-and-throw on extra keys. In Swift, Codable already ignores unknown keys, so the risk is a non-optional property added later. In Go, encoding/json ignores unknown fields unless you call DisallowUnknownFields.
2. 2

   Treat enums as open

   Model finish_reason, error type, error code and model ids as strings with a known set, plus a default branch. A switch with no default is a future outage.
3. 3

   Pin the model, not the version

   The /v1 path is stable, but which model you call is your decision. Send an explicit model id in every request instead of relying on whatever the default happens to be.
4. 4

   Branch on status and code

   Use the HTTP status code and the error code field for control flow. The message field is for humans and can be reworded at any time.
5. 5

   Log what you do not understand

   When an unknown enum member or field shows up, log it once and keep going. That log line is how you find out we shipped something before it matters to you.

Related pages

• Deprecation policy: how a surface is retired once we decide to remove it.
• API changelog: the running record of what changed and when.
• Errors: the error object and the status codes you should branch on.
• Rate limits: the 429 contract and how to back off.
• Legal: where the contractual terms governing API use are published.