Versioning
This page describes the version numbers you will encounter in Open Play (API path, protocol, plugin schema, SDK) and how the server notifies you when an endpoint or operation is being deprecated. Important: there is no written breaking-change and removal policy yet; below, only the behavior that is in the code today is described.
What each version tells you
| Version | Where it appears | Meaning |
|---|---|---|
API path /v1 | All endpoint paths | The single path version; there is no /v2 |
Realtime protocolVersion | In every frame (1) | The socket protocol major version; a different value gets UnsupportedProtocol |
Plugin protocolVersion | Schema document (1) | The major version of the plugin contract |
codecProfile | Schema document (plugin-v1-decimal-int64) | The wire encoding; a single profile for now |
Plugin version | Schema document (for example 1.44.0) | The plugin’s version text |
schemaVersion | Every operation and message definition; the x-crx-schema-version header | The schema version of a single message (a positive integer) |
schemaSha256 | Schema document | The digest of the schemas; the pinning key (bindings) |
| SDK version | Package version | TypeScript @ferdiunal/open-play-ts (0.x), Unity com.openplay.sdk (0.x) |
/v1 and the server version
All HTTP endpoints are under /v1. The server has no separate “API version” header; which endpoints exist is shown by the endpoint reference and (for core REST) GET /openapi.json. /openapi.json is a hand-compiled document that covers core REST: it does not cover plugins, WebSockets, or the panel API and may not be complete for every endpoint.
Protocol version
protocolVersion: 1 is required in realtime frames; any other value gets an UnsupportedProtocol error and the socket closes. If your client gets this error, instead of retrying ask the user to update (the TypeScript SDK moves to the upgradeRequired state in this case).
Plugin schema versions
A plugin schema is versioned at two levels:
- Operation/message level
schemaVersion: declared on every request withx-crx-schema-version. If you send a version different from what the server knows, you get400 invalid_argument. - Document level
schemaSha256: any change in the schemas changes the digest. You pin your client to this digest.
The version text (1.44.0) is informational; make the compatibility decision by the digest. For how to verify the plugin version and the digest match, see bindings.
Deprecation
When an endpoint or operation is being deprecated, it keeps working; its behavior, status codes, and body do not change. The deprecation is notified to you with these signals:
| Signal | Where |
|---|---|
The Deprecation: @<unix seconds> response header (RFC 9745) | On every deprecated response (successful or erroneous) |
OpenAPI deprecated: true | On the relevant operation in /openapi.json |
A deprecated object in the schema document | On plugin operations: since (version text), sinceUnixS, and replacement (the short name of the surface that replaces it) |
@deprecated in the SDK | On the relevant operation in the generated TypeScript binding |
What is deprecated today:
| Surface | Header value | Replacement |
|---|---|---|
/v1/auth/organization/* (player organizations, 19 endpoints) | @1793491200 (2026-11-01 UTC) | None; the organization feature is being deprecated, do not confuse it with the studio concept |
The package-ride plugin’s daily score queries (getDailyBoard, getLeaderboard) | @1793577600 (2026-11-02 UTC) | The core leaderboard (“Daily earnings”) |
The package-ride operator player view (operatorPlayer, operatorPlayers) | @1793577600 | The core character profile and list |
The header’s value gives the moment the deprecation started (UTC unix seconds); it does not give a removal date. There is no Sunset header in the response.
Warning
There is no promise such as a removal date, a minimum notice period, or “a deprecated endpoint works for at least N months”. Do not add a new dependency on a deprecated surface, and when you see the
Deprecationheader, make a migration plan. To track the header in your logs, record the response headers.
SDK versions
- The TypeScript SDK is in
0.xversions; breaking changes may occur between0.xversions. Follow each version’s changes from the package’s changelog and release notes; pin the version exactly (like0.1.15), and do not use a^range. - The Unity SDK is at version
0.1.0and is verified only with Unity6000.6.7f1(Unity SDK). - The SDK and the server evolve together: a new SDK feature (for example leaderboard, store) requires the server version that carries that feature. Do not update the SDK before the server.
- In plugin bindings, compatibility depends not on the SDK version but on the
schemaSha256pin (bindings).
What to do
- Write your SDK version and your plugin
schemaSha256values into your release manifest. - After every server update, compare the schema document and, if needed, regenerate the binding.
- Open a migration task for every call that sees the
Deprecationheader. - On a realtime and plugin protocol version mismatch, ask the user to update; do not build a retry loop.