Control API
Versioning
The protocol is velum/1, and it only grows. Ids never change and never go away, so a client written today keeps working with every later Studio.
What stays fixed
- Action and event ids never change once shipped, and none goes away. People's keys and buttons store them.
- Error codes and their names never change meaning.
- Fields are never removed or retyped. Studio may add fields to an object, and words to an enum, so accept ones you don't know.
action.runand the untypedeventnotification keep working alongside the typed methods and events.
What grows
The catalog version goes up when actions are added. The current one is 21, and Studio says its own in the hello:
{ "jsonrpc": "2.0", "method": "hello", "params": { "protocol": "velum/1", "catalog_version": 17, "…": "…" } }A client compares it with the catalog version it was built against:
| Studio's catalog is | What happens |
|---|---|
| The same | Everything the client knows is there. |
| Newer | Everything the client knows still works. Studio has more actions and events than the client: run newer actions by id with action.run (or the SDKs' run-by-id), and treat a notification whose method you don't know as an event newer than your client. |
| Older | The client knows actions this Studio doesn't have. Calling one is -32601 (method_not_found) or -32010 (unknown_action). Check catalog.list and hide what isn't there. |
The surest approach is the catalog-driven one: read catalog.list when you connect and offer what it lists. The Stream Deck plugin, Touch Portal plugin and Companion module all work that way.
The SDKs
Each SDK is generated from one catalog snapshot, and is stamped with it:
| C# | TypeScript | Python | |
|---|---|---|---|
| Catalog version | StudioCatalog.Version |
CATALOG.version |
CATALOG_VERSION |
| Fingerprint | StudioCatalog.Fingerprint |
CATALOG.fingerprint |
CATALOG_FINGERPRINT |
| Generator version | StudioCatalog.GeneratorVersion |
CATALOG.generatorVersion |
GENERATOR_VERSION |
The fingerprint is a hash of the whole catalog: equal fingerprints, identical catalogs. It tells two builds of the same catalog version apart.
Package versions are the generator's major version, then the catalog version, then a patch: catalog version 17 gives 1.17.0. A change to the generated code's shape for the same catalog bumps the generator's version.
| Language | Package | Version |
|---|---|---|
| C# | Velum.Studio.Client | 1.21.0 |
| TypeScript and JavaScript | velum-studio-client | 1.17.0 |
| Python | velum-studio-client | 1.21.0 |
This site
The reference on this site is generated from Studio's catalog version 21 when the site is built, and the build fails if the reference is older than the catalog it describes.

