Import and export dev docs - Big Spinning Wheel

Supported file formats

Format	Extension	MIME type	Contents
Big Spinning Wheel File	`.bswheel`	`application/vnd.bigspinningwheel.wheel+json`	Versioned UTF-8 JSON with wheel settings, selected sound IDs, and ordered segment definitions.
CSV segments	`.csv`	`text/csv`	Header-based UTF-8 CSV with one row per segment.
Plain text segments	`.txt`	`text/plain`	UTF-8 text with one nonblank segment label per line.

Import requests must use one of the supported format values: bswheel, csv, or text. The legacy value json is accepted for native files.

Native `.bswheel` JSON

The native file is a JSON document with format set to big-spinning-wheel and version set to the current export version, 4.

Omitted defaultable fields use the app system default on import, including replacement import. Omitted name on replacement import keeps the existing wheel name. Present null clears nullable selected sound IDs, and present null for non-nullable fields rejects import.

Field	Type	Notes
`format`	string	Use `big-spinning-wheel`.
`version`	number	Current export version is `4`. Future versions are rejected by older app nodes.
`name`	string	Optional for replacement import, required for new native imports unless a fallback wheel name is supplied. Maximum length is 120 characters.
`spinDurationSeconds`	number	Optional whole number from 5 to 60.
`spinMisdirectionMaxDecoyCount`	number	Optional whole number from 0 to 3, capped by spin duration. Requires version `3`.
`landedSegmentDisableMode`	number	`0` disabled, `1` optional, `2` forced.
`publicLandedSegmentDisableMode`	number	`0` automatic, `1` blocked. Owner-controlled on replacement import.
`resultAutoDismissSeconds`	number	`-1` means manual dismiss, `0` means do not show the result message, or use `1` through `300` seconds.
`colorPalette`	string	Optional palette id. Unknown palette ids import as the default palette.
`spinMusicTrackId`	string or null	Optional selected spin music catalog id. Requires version `4`. Non-null values must exist in the enabled sound catalog.
`spinTickPresetId`	string or null	Optional selected pointer tick catalog id. Requires version `4`. Non-null values must exist in the enabled sound catalog.
`segments`	array	Required. A wheel must have at least one segment and at most 1,024 segments.

Unsupported native fields are rejected instead of silently ignored, including legacy field names such as formatVersion, colorPaletteId, spinMisdirectionDecoyCount, and probabilityWeightUnits.

Native version history

Version	Fields	Behavior changes
`1`	Document fields: `format`, `version`, `name`, `spinDurationSeconds`, `colorPalette`, `segments`. Segment fields: `label`, `isEnabled`, `probabilityWeight`, `backgroundColor`, `borderColor`, `fontColor`.	Initial native JSON definition format. Segment-only CSV and text formats remain separate. Unsupported future fields are rejected. Exports exclude ownership, collaboration, history, and state data.
`2`	Added `landedSegmentDisableMode`, `publicLandedSegmentDisableMode`, `resultAutoDismissSeconds`.	Older native versions are accepted. Landed-disable values are enum-validated. Public landed-disable remains owner-controlled. Optional landed-disable requires a visible result message.
`3`	Added `spinMisdirectionMaxDecoyCount`.	The field requires version `3` or later. Values are capped by effective spin duration. Omitted values use default or duration-clamped behavior.
`4`	Added `spinMusicTrackId`, `spinTickPresetId`.	Selected sound IDs are portable by catalog ID only. Sound files and catalog definitions are excluded. Unavailable provided IDs fail import. Omitted fields use defaults. Nullable present-null fields clear values. Non-nullable present-null fields fail validation.

Segment fields

Field	Type	Notes
`label`	string	Required after trimming. Maximum length is 80 characters.
`isEnabled`	boolean	Optional in native files; missing values default to `true`.
`probabilityWeight`	number	Optional whole number from 1 to 1,000,000,000,000. Missing values default to 1.
`backgroundColor`	string	Optional `#RRGGBB` hex color.
`borderColor`	string	Optional `#RRGGBB` hex color.
`fontColor`	string	Optional `#RRGGBB` hex color.

When any segment color is supplied, all three color fields are required for that segment. Segments without explicit colors receive generated colors from the imported or existing palette.

Native example

{
  "format": "big-spinning-wheel",
  "version": 4,
  "name": "Lunch picker",
  "spinDurationSeconds": 12,
  "spinMisdirectionMaxDecoyCount": 1,
  "landedSegmentDisableMode": 0,
  "publicLandedSegmentDisableMode": 0,
  "resultAutoDismissSeconds": 5,
  "colorPalette": "default",
  "spinMusicTrackId": null,
  "spinTickPresetId": null,
  "segments": [
    {
      "label": "Pizza",
      "isEnabled": true,
      "probabilityWeight": 2,
      "backgroundColor": "#2563EB",
      "borderColor": "#1D4ED8",
      "fontColor": "#FFFFFF"
    },
    {
      "label": "Tacos",
      "isEnabled": true,
      "probabilityWeight": 1
    }
  ]
}

CSV segment files

CSV imports and exports use these columns: Label, IsEnabled, ProbabilityWeight, BackgroundColor, BorderColor, and FontColor. Label is required; the other columns are optional on import.

Label,IsEnabled,ProbabilityWeight,BackgroundColor,BorderColor,FontColor
Pizza,True,2,#2563EB,#1D4ED8,#FFFFFF
Tacos,True,1,,,
Soup,False,1,#16A34A,#15803D,#FFFFFF

Plain text segment files

Plain text imports read one nonblank segment label per line. Blank lines are ignored. New-wheel imports require a wheel name because text files do not carry one.

Pizza
Tacos
Soup

Import and export behavior

New-wheel import creates a private wheel for the signed-in user. Segment-only formats require a supplied wheel name.
Existing-wheel import replaces the wheel definition, not spin history, winner snapshots, stats, collaborators, favorites, public links, sound files, or catalog definitions.
Owners can import owner-controlled native fields such as the wheel name and public-link landed-disable availability. Edit-capable collaborators can replace editable content and settings, but owner-only fields stay unchanged.
Native selected sound fields carry catalog IDs only. Provided non-null spinMusicTrackId and spinTickPresetId values must exist in the destination enabled sound catalog.
Exported files include only selected wheel definition data for the chosen format. Exports exclude owner ids, collaborator rows, invite/share/public-link codes, favorites, spin history, stats, sound files, and sound catalog definitions.
Raw import file bytes are parsed during the request and are not stored as files. Imported names, labels, settings, weights, and colors become normal wheel content.

Import and export