> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions and compatibility

> The difference between v1 and v1beta, the backward compatibility policy, and how to write change-resilient clients

The Platform API carries the version in the path. Most endpoints are `v1`, and some that are still pre-stable are `v1beta`.

```
https://platform-api.trychainshift.ai/api/v1/platform/runs
https://platform-api.trychainshift.ai/api/v1beta/platform/sources/statistics/domains
```

## v1 and v1beta

| Version | Meaning | Compatibility |
| - | - | - |
| `v1` | Stable version with a finalized interface | Backward compatibility is maintained |
| `v1beta` | Pre-stable version whose interface may still change | Not guaranteed |

## Backward compatibility in v1

On `v1` paths, existing clients keep working. The following changes are considered compatible and ship without notice.

* Adding new fields to responses
* Adding optional request parameters
* Adding new endpoints
* Adding new values to enumerated fields such as model IDs, run statuses, and error `code` values

Breaking changes are never applied to `v1` paths. When needed, they ship under a new version path. Every change is recorded in the [Changelog](https://docs.trychainshift.ai/en/changelog.md).

## Using v1beta

> [!WARNING]
>
> `v1beta` endpoints are pre-stable. Response fields, request parameters, and
> paths may change or be removed without notice.

If you depend on a beta endpoint in production, we recommend the following.

* Keep the call sites in one place. When a path or response changes, there is less to fix.
* Instead of storing responses as-is, extract only the values you need and store them in your own schema.
* Subscribe to the [Changelog](https://docs.trychainshift.ai/en/changelog.md). An RSS feed is available.

When a beta endpoint is promoted to `v1`, it is announced in the Changelog.

## Checking the version of an endpoint

If the request path contains `/v1beta/`, the endpoint is beta. The actual path is shown at the top of each [API Reference](https://docs.trychainshift.ai/en/api-reference/overview.md) page.

> [!NOTE]
>
> Versions are promoted per resource. Even when they handle the same data,
> endpoints can have different versions, such as answer retrieval
> (`/v1/platform/answers`) and source statistics
> (`/v1beta/platform/sources/statistics/domains`).

## Change-resilient clients

* **Ignore unknown fields.** Parsing must not fail when a new field is added to a response. Turn off strict deserialization settings that error on unknown keys.
* **Do not assume a field is always present.** A field may be missing from a response depending on whether you requested it with the `include` parameter and whether data exists.
* **Be ready for unknown values.** New values may be added to model IDs, run `status`, and error `code`. Add a default branch to your conditionals.
* **Keep the version path in a constant.** If you do not hardcode `/api/v1/platform` throughout your code, a promotion only requires a change in one place.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.