Historical API55 integration guide. Use the final dev58 OpenAPI and current handoff for crowd additions and current limits.

Roster fields and match context

Roster Studio supports optional standard college fields and versioned custom fields. All are optional; your app can consume the companion through the public broker without parsing native memory. D1/D2/D3/NAIA, school and previous-college context, conference identities and rankings belong here. Expanded conference identities do not imply an expanded native two-conference selector.

Intake and identity

Export the complete ZIP from https://openhoops.io/rostereditor, or keep its ROS and adjacent .openhoops.json together. The companion is bound to the exact ROS hash and size. Re-export after editing; do not attach a companion from a different binary revision. The request accepts roster.archive_path, an adjacent companion, or explicit roster_metadata with a checked path/hash or registered ID. Optional player_rows maps every planned slot to its physical record where required by the context resolver.

Standard field definitions and types are available through GET /v1/roster-metadata/catalog. Query registered companions with POST /v1/roster-metadata/query; resolve checked team/player/arena context with /v1/roster-metadata/resolve. The snapshot carries a context reference. The bound managed match and immutable final result retain the frozen context and its identity, so later editor changes do not silently rewrite a past game's facts.

Custom definitions use the versioned companion format, typed values and namespaced identifiers. Retain unknown fields rather than deleting them because your app does not recognize them. Metadata never changes native ratings, names or rule mechanics by itself. An editor field with a future presentation meaning is data until a consumer implements it.

Match overrides and event/round captions

An app can supply match-specific overrides separately from reusable roster metadata. For event/round graphics, use identity.metadata["org.openhoops.presentation"] with format:"openhoops.match_presentation" and version:1, as documented in the context contract. It covers event name, round, compact/full caption and subtitle; e.g. Maui Invitational / Championship or NCAA Tournament / Sweet 16. Use the supplied validator/authoring helper contract rather than guessing field names. The context hash is separate from the roster hash.

This transports the facts for a future scorebug; it does not draw a scorebug. Presentation observations must not be relabeled as a verified replay/award timeline.

In-process native access

HTTP clients need no native DLL. Trusted x86 mods may use native/sdk/openhoops_metadata.h to copy committed metadata. Opt in with launch_configuration.native_metadata:true when startup must hold before reveal until the native mapping is committed. A consumer validates format/version/bytes, run/match identity, context hash, bounds and integrity; never retain a pointer into a changing mapping. Native metadata is read-only, not a second roster writer.

The independent C example is in api/examples/native_metadata. This exact hook's original/college tests verified strict independent C reads before play, metadata identities in final results and zero adapter/module faults. This establishes data access, not rendered broadcast graphics. The broker builds the companion context; the game DLL does not parse the editor JSON.