Seat Preevue developer docs

Schemas

Every object the public operations send or return.

Alias

Field Type Required Description
type string: one of legacyKey, legacyBaseUrl, origin, spektrixClient, spektrixVenue, tessituraVenue, criterionFacility, tixlyVenue, other yes legacyKey, legacyBaseUrl and origin are globally unique; the rest are unique within a tenant.
value string yes
imagerySet string

ApiKey

Field Type Required Description
id string
tenantId string
type string: one of publishable, secret
scope string: one of tenant, admin
label string
prefix string
status string: one of active, revoked, scheduled_revoke
allowedOrigins array of string
allowOriginOnly boolean
embed object
venueIds array of string
venueImagerySets VenueImagerySets Per venue id, the imagery sets a key may use (1.11.0); a venue not listed: every set the tenant may use. Intersected with the grant where the set is chosen. At most 200 venues, 50 sets each. null or {} clears.
kind string: one of secret, publishable, keyless keyless is a publishable key with allowOriginOnly (1.11.0).
rateLimit object
createdAt string (date-time)
updatedAt string (date-time)
lastUsedAt string (date-time) The last successful authentication, to within a minute (1.11.0).
revokeAt string (date-time)
revokedAt string (date-time)
rotatedFrom string The key this one replaced, when a rotation issued it.

ApiKeyWithSecret

Type: ApiKey and object

CreateKeyRequest

Field Type Required Description
tenantId string Admin scope only; defaults to the caller's tenant.
type string: one of publishable, secret yes
scope string: one of tenant, admin admin requires an admin-scope caller.
label string yes
allowedOrigins array of string
allowOriginOnly boolean
embed object
venueIds array of string Required for publishable keys.
venueImagerySets VenueImagerySets Per venue id, the imagery sets a key may use (1.11.0); a venue not listed: every set the tenant may use. Intersected with the grant where the set is chosen. At most 200 venues, 50 sets each. null or {} clears.
rateLimit object

CreateSessionRequest

Field Type Required Description
sessionId string Extend this session instead of creating one.
context SessionContext What your page or platform knows. venueRef is matched against the venues' references for platform, within the venues your key may use; then the venue's layout rules are evaluated over the other facts. With no context, the key's single venue is used.
locale string Overrides the venue locale for labels.
embed object
consent boolean Host has obtained consent for persistent identifiers.
sdk object

Event

Field Type Required Description
type string: one of open, view, view_complete, unavailable, error, close, ad_shown, exposure, seat_selected, seat_added, checkout_reached yes
ts string (date-time) yes
venueId string
imagerySet string
seatKey string
durationMs integer
experimentId string
variant string
parentOrigin string Embeds only.
error object
props object ≤ 1 KB; no personal data.

EventBatch

Field Type Required Description
sessionId string yes
eventsToken string Server sessions only (no Origin); the Session.eventsToken issued when the session was created. Browser sessions omit it.
events array of Event yes

LayoutFact

Type: string: one of attributes, sections, labels, zones, mapId, productionId

LayoutRule

Ordered; first match wins; no match → the venue's default set. Exactly one of imagerySet or venueId. Patterns are case-insensitive, evaluated with RE2 (linear time), max 200 chars. Guide §5.2.

Field Type Required Description
when object yes All present conditions must hold.
imagerySet string
venueId string Rare: switch to another venue of the same tenant, for a layout that needs different seat-key rules, named views or ads. Layouts of one room are normally imagery sets.

Manifest

Field Type Required Description
version integer yes
set string
generatedAt string (date-time)
seats array of string yes
namedViews array of string
tile object
preview object

NamedView

Field Type Required Description
id string yes
label string yes
key string yes
showFor object When adapters should offer it, e.g. { area: "Gallery" }.

Normaliser

strip-trailing-seat (1.8.0) drops a final word "seat", then slugs: "Table 6 Seat " → table-6.

Type: string: one of slug, strip-whitespace, spaces-to-hyphen, first-space-to-hyphen, strip-trailing-seat, lower, none

Problem

Field Type Required Description
type string (uri) yes
title string yes
status integer yes
detail string
pageStart boolean On venue_not_found from createSession only (1.12.0): false when page-start is switched off for the caller's partner or everywhere, so the script hides nothing for an unknown venue either. Absent otherwise.
code string: one of invalid_key, key_revoked, scope_insufficient, origin_not_allowed, origin_missing, session_not_found, venue_not_allowed, venue_not_found, alias_conflict, conflict, set_not_found, seat_not_found, rate_limited, validation_failed, internal

ResolvedSeat

Field Type Required Description
matched boolean
key string
candidates array of string
unmapped string: one of area 1.8.0. The seat's areaRef isn't in the session plan's maps entry (1.11.0) nor the venue's seatKey.areaRefs.
previewUrl string (uri) Signed. Absent when the set has no previews (some sets have none) or the seat has no key.
configUrl string (uri) Signed.
basePath string For multiRes.basePath; no trailing slash.
extension string For multiRes.extension, e.g. "jpg?Policy=…".

SeatKeyRules

Guide §5.2–5.3.

Field Type Required Description
templates array of string Tried in order. Tokens {section} {row} {seat} {area} {screen} {zone} {label} {suffix} {venueSlug}; templates with a missing token are skipped.
normalise object Per-token normaliser; default applies to tokens not listed.
trimChars string Characters stripped from token ends, e.g. "*".
sectionAliases object Raw section → canonical. Keys may be a section name, screen:<n>, or *.
remap object
areaRefs object 1.8.0. Platform area id (verbatim) → the raw tokens it stands for, normalised like any other token; {} marks an area as known without adding a token. A seat sent with an areaRef not listed here resolves to nothing (ResolvedSeat.unmapped: area), so an unmapped area never shows another area's view.
seatRefs object 1.8.0. Platform seat id (verbatim) → asset key, tried before every template (still checked against the manifest).

SeatRef

The SDK also accepts a bare string as shorthand for { key }.

Type: object or object or object

SeatTokens

Field Type Required Description
section string
row string
seat string
area string
screen string
zone string
label string
suffix string
venueSlug string
areaRef string A platform area id (Spektrix Seat Picker areaId), looked up verbatim in seatKey.areaRefs. Never normalised or used in templates. 1.8.0.
seatRef string A platform seat id (Spektrix seatId), looked up verbatim in seatKey.seatRefs. 1.8.0.

Session

Field Type Required Description
sessionId string yes
tenant object yes
venues array of SessionVenue yes
cdn object yes
viewerAssets object yes
labels object yes The words the SDK and the adapters show visitors, in locale. Every key below is always present; more may be added, so a client ignores keys it doesn't know.
locale string yes The locale labels are in: the request's locale (exact tag, then its language), then the first venue's locale the same way, then en-GB. Only en-GB exists yet.
experiment , or null or object
ttlSeconds integer yes
expiresAt string (date-time) yes
eventsToken string matching ^[A-Za-z0-9]{32}$ Server sessions only (an sk_ key, no Origin), and only in the response that created the session: the /events credential for this session. Shown once; Seat Preevue stores only its hash. The backend hands it, with sessionId, to its app.

SessionContext

What your page or platform knows. venueRef is matched against the venues' references for platform, within the venues your key may use; then the venue's layout rules are evaluated over the other facts. With no context, the key's single venue is used.

Field Type Required Description
platform string: one of spektrix, tessitura, syos, criterion, tixly, lineup, atg, atlas, other
venueRef string Any alias value — legacy venueKey verbatim, Tessitura venue ID, Criterion facility ID, Spektrix client, origin — or a venue id (ven_…), tried after every alias type and held to the same access checks; an alias with the same value wins.
legacyBaseUrl string Legacy shim only — a base URL primed into SeatPreevue.baseUrlCache by a caller.
eventRef string Platform event/instance ID (attribution only).
productionId string
attributes object Platform event attributes (e.g. Spektrix Preevue = "with surtitle").
sections array of string Section names from platform data (Spektrix sections, TNEW GetSeatList section_desc).
labels array of string Visible layout text on the host page (TNEW screen buttons and section headings).
zones array of integer
mapId string Platform seat-map ID, e.g. TNEW smap-419, Spektrix seatInfo.planId. Selects the venue's maps entry (1.11.0); the session stores it, and resolveSeats uses that map's areaRefs/seatRefs first.
imagerySet string The layout chosen by the partner for this event (e.g. Line-Up, which today sets a base URL per event, sets a layout name such as wrestling). Must name one of the venue's imagery sets, else 400 set_not_found. When present, layout rules are not evaluated.
unavailableFacts array of LayoutFact Facts the adapter looked for (after waiting a bounded time) and could not collect; rules needing them are skipped until a later extend supplies them.

SessionVenue

Field Type Required Description
id string yes
label string yes
imagerySet object yes
seatKey SeatKeyRules yes Guide §5.2–5.3.
namedViews array of NamedView
platformParams object Platform IDs the adapter needs to collect facts, e.g. { tessitura: { facilityId: 408, screenId: 2 } } for the GetSeatList probe.
layout object Outcome of layout-rule evaluation for this venue.
viewer object
ads object
pageStart boolean Page-start mode may act for this venue (1.12.0): false when switched off for the venue (VenueRecord.pageStart), the partner (features.pageStartOff) or everywhere (Preevue's tenant). The script then changes nothing on the page.
planServed boolean Present when the context named a mapId (1.12.0): false exactly when the layout choice logged plan_unmapped (the venue lists maps and none of them, a layout rule, a requested imagerySet or an alias pinning a set serves the plan). Page-start hides the view button for it; a click still gets the venue's default set.

Tenant

Field Type Required Description
tenantId string
name string yes
status string: one of active, suspended
createdAt string (date-time)
updatedAt string (date-time)

UpdateKeyRequest

Field Type Required Description
label string
allowedOrigins array of string
allowOriginOnly boolean
embed object
venueIds array of string
venueImagerySets VenueImagerySets Per venue id, the imagery sets a key may use (1.11.0); a venue not listed: every set the tenant may use. Intersected with the grant where the set is chosen. At most 200 venues, 50 sets each. null or {} clears.
rateLimit object
status string: one of active, revoked

VenueImagerySets

Per venue id, the imagery sets a key may use (1.11.0); a venue not listed: every set the tenant may use. Intersected with the grant where the set is chosen. At most 200 venues, 50 sets each. null or {} clears.

Type: object, or null

VenueMap

1.11.0. One plan's entry in VenueRecord.maps.

Field Type Required Description
label string For people (the console).
imagerySet string yes One of the venue's imagerySets.
areaRefs object The plan's own areas, the same shape as SeatKeyRules.areaRefs; tried before the venue's.
seatRefs object The plan's own seat overrides, the same shape as SeatKeyRules.seatRefs; tried before the venue's.
addedAt string (date-time)
addedBy string The key that first wrote the map.

VenueRecord

Field Type Required Description
venueId string
tenantId string
label string yes
locale string
status string: one of live, staging, archived
aliases array of Alias yes
imagerySets object yes
layoutRules array of LayoutRule
seatKey SeatKeyRules yes Guide §5.2–5.3.
namedViews array of NamedView
platformParams object
viewer object
ads object Admin scope only (1.10.0); a tenant key may send the current value back unchanged, otherwise 403 scope_insufficient.
pageStart boolean Page-start for this venue (1.12.0). Absent: on; only false is stored. Admin scope only: a tenant key's value is ignored and the stored one kept. Omitted from a replaceVenue: kept.
maps object 1.11.0. Per seating plan or map (SessionContext.mapId; Spektrix's planId), keyed by its id (1 to 64 letters, digits, _ or -): the plan's imagery set and its own area and seat maps, tried before the venue's. Absent: the venue behaves as before 1.11.0. Omitted from a replaceVenue: the stored maps are kept; {} removes them.
version string
access object How the caller holds the venue (1.9.0): owner, grant (read-only to the grantee; imagerySets the granted sets, absent = all) or admin.
grantAliases array of Alias and object Admin views only (1.9.0) — other tenants' own aliases on the venue.