Gateway Payloads Falcon Play

Technical reference for what Falcon Play sends to gateway.wearefalcon.tv during asset export and rundown trigger sync.

Overview

Falcon Play communicates with the gateway in two separate flows:

Asset export to https://gateway.wearefalcon.tv/assets/ as MOS XML.
On-air trigger sync to https://gateway.wearefalcon.tv/triggers/{token} as JSON.

Flow	Protocol	Payload format	Purpose
Asset export	HTTPS POST	XML (MOS 2.8 + `mosExternalMetadata`)	Transfer selected Video/Graphics/Functions/Inputs including metadata.
Trigger sync	HTTPS POST	JSON	Update Falcon Rundown on-air status and current story id.

Asset Export Endpoint

POSThttps://gateway.wearefalcon.tv/assets/

Request headers

Header	Value	Description
`Content-Type`	`application/xml; charset=utf-8`	MOS XML payload.
`X-Falcon-ProjectID`	Configured Asset Package ID	Project scope for gateway ingestion.
`X-Falcon-AssetKind`	`SERVER`, `GRAPHIC`, `FUNCTION`, or `CAM`	Asset category for this export batch.

MOS envelope

<mos version="2.8">
  <mosID>falcon-play</mosID>
  <ncsID>falcon-rundown</ncsID>
  <messageID>falcon-{type}-{timestamp}</messageID>
  <roProjectID>{projectId}</roProjectID>
  <mosExternalMetadata>
    <mosScope>PLAYLIST</mosScope>
    <mosSchema>http://wearefalcon.tv/schema/falconAssets.xsd</mosSchema>
    <mosPayload>
      <falconAssets type="{ASSET_TYPE}" jsonSource="{kind}.json">
        ... one or more <asset> nodes ...
      </falconAssets>
    </mosPayload>
  </mosExternalMetadata>
</mos>

Asset types mapping

Falcon Play kind	Gateway assetType
`video`	`SERVER`
`graphic`	`GRAPHIC`
`functions`	`FUNCTION`
`input`	`CAM`

Metadata transport rules

Each exported <asset> contains:

Typed core fields for that asset category (for example name, fileName, path, duration, variables, actions).
<metadata> with flattened <field key="...">...</field> entries for extended metadata.
<metadataJson encoding="json">...</metadataJson> with complete JSON metadata for lossless transport.

Falcon Play merges canonical export data before sending. For example, video export combines Media Server cache data with local videos extra config metadata so metadata fields are preserved in export payloads.

Trigger Sync Endpoint

POSThttps://gateway.wearefalcon.tv/triggers/{token}

Request headers

Header	Value
`Content-Type`	`application/json`

JSON payload

{
  "on_air_flag": 1,
  "on_air_story_id": "STORY-123", 
  "on_air_time": "2026-06-14T12:34:56.000Z"
}

Field behavior

Field	Required	Rule
`on_air_flag`	Yes	Primary state flag.
`on_air_story_id`	Conditional	Sent only when `on_air_flag = 1` and story id exists.
`on_air_time`	No	Included when timestamp is available.

Error Handling and Retries

Asset export and trigger sync are sent via HTTPS worker threads.
HTTP status and response text are returned back to Falcon Play UI/status events.
Asset export worker timeout default is 30 seconds (Falcon Play export job uses 45 seconds).

Operational Notes

Autosync export only sends when dataset hash changes, reducing duplicate uploads.
Manual export can target selected items; selected payloads are resolved against canonical datasets before XML generation.
Project ID must be configured (falconRundownAssetID) for gateway asset export.